术语解释（全局汇总）

本页汇总文章中出现的术语解释，作为全局统一口径与快速查阅的参考。

BFF（Backend For Frontend）

面向前端的服务层：承载路由治理、缓存、灰度与观测等跨切面能力，避免规则散落。

Custom Server

自定义服务层（如 Express）承载框架请求处理；用于在进入页面渲染前做统一治理。

rewrite

内部映射：URL 对外不变，但内部路由指向新页面；适合迁移早期与上线不同步兜底。

redirect（301/302）

外部跳转：客户端被引导到新 URL。301(永久) 常用于 SEO 收敛；302(临时) 常用于短期跳转或灰度。

重定向链长

一个请求连续跳转的次数。链越长，体验越差、SEO 风险越高；出现循环时链长会无限增长。

canonical

规范化链接：通过 <link rel="canonical" href="..." /> 声明主版本 URL。要求稳定（无 query/hash）、最终（指向 200） 且与 hreflang 口径一致。

soft 404（软 404）

页面返回 200 但内容无效/空/不匹配，搜索引擎判定为 404。路由迁移与内容缺失时很常见。

灰度发布（Gray release）

分批放量上线：从小比例/小范围开始，观察指标无异常再扩大；用于降低迁移风险并便于回滚。

TTFB（Time To First Byte）

首字节时间：从发起请求到浏览器收到响应第一个字节的时间；在 SSR 场景下通常最能反映“服务端渲染/回源”带来的延迟。

p95（95 分位）

把一批导出样本按耗时/体积排序，取 95% 位置的值。用来衡量“绝大多数用户”的体验，比平均值更靠谱。

Chakra UI Theme

通过 extendTheme 定义全局样式体系（foundations/semanticTokens/components），由 ChakraProvider 注入应用。

foundations（global scales）

基础尺度：colors/space/radii/fontSizes/lineHeights/textStyles 等，用于统一“值”。

semantic tokens

语义 token：表达“用途/语义”而不是具体值（例如 bg.panel、text.fgMuted），并支持暗黑映射。

variants（组件变体）

组件层契约：把常用样式组合封装成有限集合（例如按钮的 solid/subtle/outline），避免业务页面手写交互状态。

cssVarsRoot

Chakra 的 CSS 变量根挂载配置。用于让 portal 容器与预览容器也能拿到正确的 token 变量。

portal

弹层类组件常用的渲染方式：内容被渲染到 DOM 的另一个节点（例如 body 下）。如果 token 变量根不覆盖，会导致样式漂移。

散装值

直接写在业务代码里的 raw 值（hex/rgba/px）。它们会让一致性与主题演进成本指数上升。

视觉回归（visual regression）

通过截图/像素 diff 等方式验证“样式变更是否符合预期”，是 Token 变更上线的关键安全网。

Design Token

用结构化方式表达设计决策（颜色、间距、圆角、字号、阴影等）的“最小可复用单位”，可被多端消费。

global token（基础/原子 token）

具体数值层（色板、尺寸、字重）。它解决“值统一”，但不直接表达业务语义。

semantic token（语义 token）

语义层映射（bg/text/border 等）。它解决“语义统一”，是暗黑模式与主题演进的关键承载层。

component token / variants

组件层契约：用有限的变体集合表达常用样式组合，降低业务页面自由拼装导致的不一致。

alias（引用/别名）

Token 指向另一个 token（例如 bg.panel 指向 gray.950）。用于复用与迁移。

CSS variables（CSS 自定义属性）

Token 在运行时的一种常见承载形式（例如 var(--chakra-colors-...)），便于主题切换与动态引用。

pdf-lib

一个用 JavaScript 创建与编辑 PDF 的库。本文用它创建页面、绘制文本/图片/形状，并嵌入字体。

fontkit

一个字体解析与度量工具。本文用它做字符级 glyph 测量（宽度）、缺字检测与字体回退决策。

pt（points）

PDF 常用的物理单位：1 inch = 72 pt。本文把 slide 的 px 映射到 pt，把 IR 的 inches 映射到 pt。

IR（Intermediate Representation，中间层模型）

导出链路里“与格式无关”的数据结构：slide 列表、元素类型、位置尺寸、样式与资源引用。两种导出通道共享 IR 才能谈一致性。

glyph / notdef

glyph 是字体里的字形；notdef 表示“字体里没有这个字符的字形”，通常会渲染成空框。缺字必须靠 fallback 字体兜底。

Font Subsetting（字体子集化）

只嵌入文档实际用到的字符集合，从而显著降低 PDF 体积；否则字体全量嵌入会导致体积膨胀。

BiDi（Bidirectional text，双向文本）

当同一行中混有 RTL 与 LTR 字符（例如阿拉伯语 + 数字/英文）时的排序规则。PPTX/PDF 的表现可能不同，需要专项回归样本覆盖。

RTL / LTR

从右到左 / 从左到右的书写方向。本文用 rtlMode 决定对齐映射，并影响列表符号位置等策略。

grapheme（字素簇）

用户感知的“一个字符单元”（例如某些 Emoji 是多个 code point 组合）。超长 token 断行时按 grapheme 分割更稳。

clipping path（裁剪路径）

PDF 中用于裁剪绘制内容的路径。本文用它实现图片 cover 裁剪与圆角裁剪。

PPTX

PowerPoint 文件格式。通常以“可编辑”为目标，因此更适合保留文本/形状而不是整页位图。

PDF

文档交换格式。适合分发与打印，但不同阅读器会带来字体渲染差异，因此更依赖你在导出阶段把布局算清楚。

px / in / pt

px 是屏幕像素，in 是英寸，pt 是 points（1in=72pt）。统一单位映射是导出一致性的几何底座。

DPI / PPI

常用于描述位图清晰度。工程里更实用的是“导出时 rasterize 的像素倍率”，倍率越高越清晰但体积也越大。

字体子集化（Font Subsetting）

只把文档实际用到的字符集合 embed 进 PDF，从而显著降低体积；否则每种字体全量嵌入会导致文件膨胀。

像素 diff / pHash

把导出结果渲染成图片后对比差异的回归方法。像素 diff 精确但敏感，pHash 更鲁棒但只能当辅助指标。

PptxGenJS

一个用 JavaScript 生成 PPTX 的库。本文用它在浏览器端创建 slide，并添加 text/image/shape。

run / text runs

富文本拆分后的最小片段：每个 run 绑定一段文本和一组样式（bold/underline/color/highlight 等）。

text-align: start / end

逻辑对齐（随书写方向变化）。在 RTL 下 start 通常对应 right；在 LTR 下 start 通常对应 left。

px / pt / in

px 是屏幕像素，pt 是 points（常用于字体大小），in 是英寸。本文建议用固定设计宽度把 px 换算到 in，让 PPTX 坐标更稳定。

bullet（列表符号）

无序列表的符号或有序列表的编号。RTL 下 bullet 的“外侧”位置更容易出错，需要显式建模。

base64 Data URL

把图片编码为 data:image/png;base64,... 的形式，便于在浏览器端直接塞进导出产物；但需要清洗与 mime 猜测以保证兼容。

Custom Server（自定义服务层）

用 Express 等框架包住 Next.js 的请求处理（而不是直接用内置 server）；适合做路由治理、服务层缓存与统一观测。

SSR（Server-Side Rendering）

服务端渲染：服务器生成 HTML 返回；热点 SSR 页面重复渲染会直接推高 TTFB。

p95（95th percentile）

95 分位：将一批请求按耗时从快到慢排序，95% 的请求耗时不超过该值；比平均值更能代表“尾部慢请求”的体验与稳定性。

HTML 缓存

缓存最终 HTML 响应；命中时可跳过 renderToHTML 的成本，但对正确性边界更敏感。

LRU Cache

最近最少使用淘汰缓存：用容量上限控制内存；适合存放热点页面的 HTML。

TTL（Time To Live）

缓存过期时间：到期自动失效；用它可以避免内容长期不更新，也便于初期试运行。

缓存键（Cache Key）

决定“哪些请求共用同一份缓存”的唯一标识；凡是会影响 HTML 输出的输入（host/locale/query/cookie/headers）都要进入 key 或绕过。

renderToHTML

Next.js 在服务端生成 HTML 的关键调用（概念名）；HTML 缓存命中时可以直接跳过这一步。

x-cache（HIT / MISS）

常见观测信号：通过响应头标记是否命中缓存，方便用 curl/日志/指标验证优化是否生效。

命中率（Hit rate）

HIT / (HIT + MISS)。按路由维度拆分后，你能快速判断“哪些页面值得缓存”以及“是否被 query/维度打碎”。

回源（Origin render / fallback）

未命中缓存时触发的真实 SSR 渲染或上游请求。优化目标通常是减少回源次数，并降低回源路径的 p95 TTFB。

Headless CMS

无头 CMS：内容存储与编辑在 CMS，前端/站点以 API/数据形式消费内容，不绑定特定渲染层。

内容管道（Content Pipeline）

把内容从 CMS 变成“可交付产物”的工程流程：同步、校验、归一化、产物生成、发布与回滚。

build-time

构建期：在 CI/构建流程中把内容同步为本地快照（便于追溯与回滚）。

runtime

运行时：在 SSR/ISR 请求链路中拉取或加载内容，支持更及时更新与预览，但必须具备降级兜底。

SSR / ISR

服务端渲染/增量静态再生：内容可以在请求时生成或按 revalidate 周期刷新，是 runtime 通道常用机制。

manifest（路由清单）

内容路由的集合输出：列出 slug、prefixPath、locales 等，供 sitemap/路由治理/批量校验使用。

requireAllLocales（语言齐全 gate）

生产环境约束：只有覆盖所有站点语言的内容才进入公开集合（sitemap/alternates），避免向爬虫宣告缺语言页面。

draft / published

草稿/已发布：非生产环境可读取 draft 以便预览；生产环境只读取 published，并结合 is_active 等状态门禁。

snake_case / camelCase

字段命名风格：内容端常见 snake_case，前端常用 camelCase。管道需要统一归一化，避免到处写兼容代码。

软 404（soft 404）

页面返回 200 但内容无效/空/低质量，搜索引擎可能判定为 404。内容管道需通过 schema 校验与资源同步降低此风险。

可追溯 / 可回滚

内容同步产物带版本与时间戳，发布物绑定版本；事故时可以快速回到上个快照，并用指标验证恢复。

hreflang（alternate link）

多语言互链声明：通过 <link rel="alternate" hreflang="..." href="..." /> 表达“同一页面的不同语言版本”。 关键在于集合准确且对称（return links）。

x-default

hreflang 的特殊值：表示默认/兜底版本。通常指向默认语言 canonical（或稳定的语言选择页）。

noindex

不收录：通过 <meta name="robots" content="noindex" /> 表达“允许抓取但不进入索引”。常用于私有页、低质量页或内容不齐的语言版本。

default locale

默认语言：通常无 URL 前缀（例如 /path），并作为 x-default 的指向。

locale prefix

语言前缀：用 /{locale}/path 表达非默认语言版本（例如 /fr/path）。

return links

回链/互链回指：hreflang 集合应当对称。A 页面声明了 B 为 alternate，B 页面也应该声明 A，否则搜索引擎可能提示 hreflang 缺 return links。

URL 归一化（Normalization）

把同一内容的 URL 形态统一：去 query/hash、统一尾斜杠、剥离 locale 前缀得到“语言无关 path”。

asPath / pathname（Next.js Router）

常见路由字段：asPath 更接近用户真实访问路径（可能包含 locale 前缀与查询参数）；pathname 可能是路由模板（如 /[slug]）。 生成 canonical/hreflang 时通常应以归一化后的 asPath 为输入，而不是直接用 pathname。

重复收录（Duplicate）

同一内容以多个 URL 进入索引。常见于 URL 规范不一致、canonical/hreflang 冲突或迁移期信号混乱。

SSOT（Single Source of Truth）

单一真相：路由清单只维护一份，并被 rewrites/Custom Server/sitemap 复用，减少分叉与回滚成本。

i18n（Internationalization）

国际化：本文语境下主要指 locale 前缀规则（如 /{locale}/...）与默认语言策略，它会影响 URL 生成与 hreflang 输出。

locale

语言/地区标识（如 en、fr）。本文假设 URL 策略使用 /{locale} 前缀表达非默认语言。

hreflang

多语言 alternate 声明：告诉搜索引擎不同语言版本之间的关系。只有页面真实存在时才应输出对应 hreflang。

alternate link

语言版本链接：<link rel="alternate" hreflang="..." />。必须只输出真实存在的语言 URL。

robots.txt

抓取规则文件：通过 Disallow/Allow 等规则控制哪些路径可被抓取。它不等价于 noindex。

sitemap.xml

站点地图：向搜索引擎声明“哪些 URL 应该被抓取”。工程化的 sitemap 需要一致性、降级与回归能力。

next-i18next

Next.js 上常用的 i18n 集成库，提供 serverSideTranslations 与 useTranslation 等能力。

locale prefix（URL 语言前缀）

把语言体现在 URL 路径中（例如 /ja/...）。对 SEO 与分享更友好，但需要统一 canonical/hreflang 口径。

defaultLocale

默认语言。常见策略是默认语言不带前缀（根路径 /），非默认语言带前缀。

localeDetection

Next.js i18n 的自动语言检测与重定向开关。关闭后，访问 / 不会再根据浏览器语言自动跳转到某个 locale 前缀。

NEXT_LOCALE

常见的语言偏好 Cookie 名称。本文用它保存用户选择的语言，用于应用页在刷新后保持一致。

Accept-Language

浏览器请求头，表示用户的语言偏好列表。可用于“首次访问”的语言匹配，但不建议无条件用于 SEO 入口的自动跳转。

hreflang / x-default

SEO 信号：声明同一内容的不同语言版本之间的对应关系。x-default 通常指向默认语言或中立入口。

redirect loop（重定向死循环）

请求在多个 URL 之间反复跳转，最终失败或被浏览器/爬虫终止。本文给出 sitemap.xml 在 i18n 下的一个典型循环与守卫修复。

SEO

搜索引擎优化：本文语境下主要指“URL 语义、收录一致性、避免重复页面与软 404”。

slug

路径片段的语义化标识（如 /tool-a 中的 tool-a）。工具页矩阵通常以 slug 扩展入口。

sitemap

站点地图：向搜索引擎声明应抓取的 URL 集合。本文建议它与路由表复用同一份清单，避免分叉。

Observability（可观测性）

系统从外部暴露足够信号，让你能回答“发生了什么、为什么、影响谁、下一步做什么”的能力。本文强调“反馈闭环”。

RUM（Real User Monitoring，真实用户监控）

基于真实用户会话采集性能与体验指标（如耗时分位数、资源失败率）。比实验室数据更贴近线上真实分布。

event envelope（事件信封/统一载体）

把 release/route/locale/session 等关联键固化进每条事件/异常的公共字段，使事件能被串联与分桶。

correlation keys（关联键）

用于把不同平台的信号串起来的键，如 user_id、session_id、trace_id、doc_id、feature_flag 等。

breadcrumb（面包屑）

异常发生前的一串关键动作记录（点击、路由切换、请求），用于还原“发生前用户做了什么”。

trace / span

链路追踪的概念：trace 表示一次端到端请求链路，span 表示其中一个步骤。前端常用于关键操作的耗时分解。

采样（sampling）

只采集部分事件/会话来控制成本与噪声。建议对“失败事件/关键链路”提高采样，对“普通事件”降低采样。

PII（Personally Identifiable Information）

可识别个人的信息（如 email、手机号）。本文建议默认不采集，必要采集要脱敏/哈希。

MTTD / MTTR

MTTD（Mean Time To Detect）平均发现时间；MTTR（Mean Time To Repair）平均修复时间。用于衡量可观测闭环是否真的在提升工程效率。

Sentry（错误监控）

用于采集异常、堆栈、版本回归与聚类分析的工具。本文强调：用 tags 分桶、用 extra 补上下文。

PostHog（产品分析）

用于采集事件、漏斗、分群与行为分析的工具。本文强调：关闭过度 autocapture，用统一 schema 串联关键链路。

event envelope（事件信封）

每条事件/异常都携带的公共字段集合（release/route/locale/session/trace/doc），用于跨平台关联与分桶。

clicked / completed / failed

关键链路三件套事件。clicked 表示意图，completed/failed 表示结果；缺失 failed 会导致定位与优先级判断失真。

PII / 脱敏（redaction）

PII 是可识别个人的信息（email/手机号等）。脱敏是指在上报前移除或哈希这些字段，避免隐私与合规风险。

抓取（Crawl）

爬虫访问并获取页面内容的过程。robots.txt 主要影响抓取。

收录（Index）

搜索引擎把页面加入索引库并可能参与排名的过程。noindex 主要影响收录。

Disallow

robots.txt 指令：禁止抓取某路径前缀。注意：禁止抓取不代表一定不收录。

crawl budget（抓取预算）

搜索引擎分配给你站点的抓取资源。把不该收录的页面塞进 sitemap 会浪费预算。

索引污染

不该出现在搜索结果里的页面进入索引（如私有页、功能页、薄内容页），影响品牌与 SEO 质量。

参数页（parameter URL）

带 query 参数的 URL（如 utm、筛选、分页）。很多场景下它们会制造重复内容，需要 canonical/noindex/重定向治理。

X-Robots-Tag

响应头形式的 robots 指令（如 X-Robots-Tag: noindex），常用于 PDF 等非 HTML 资源。

nofollow

链接关系：常见于 rel="nofollow"（多用于外链治理）。它不是页面级 noindex 的替代。

rtlMode

工程中的方向开关：通常由 locale 推导，用于决定 base direction、对齐映射、列表规则等。

shaping（连写整形）

阿拉伯语等脚本需要根据位置改变字形并发生连写；不做 shaping 会导致显示不正确。

embedding levels

BiDi 算法的中间结果，用于决定每个字符在视觉顺序中的方向与重排规则。

mirror punctuation（标点镜像）

RTL 环境下部分标点需要镜像显示（例如括号）。即使做了重排，不做镜像也会“看起来反了”。

notdef（缺字）

字体里没有某个字符的字形时的占位 glyph，常见表现是空框。缺字应由 fallback 字体兜底，并计入缺字率指标。

像素 diff

把导出结果渲染成位图，与基准图逐像素对比。可用于自动回归，但需设置容差以抵抗阅读器差异。

SEO Meta

页面 head 中输出的一组 SEO 信号集合：title/description/OG/robots/noindex/canonical/alternates 等。

TDK（Title / Description / Keywords）

三件套：标题、摘要、关键词。关键词对现代搜索的权重因引擎而异，但在工程上仍是“信息结构”的一部分。

Open Graph（OG）

用于社交分享预览的一组 meta（如 og:title、og:description、og:image）。

hreflang / alternates

多语言互链声明：<link rel="alternate" hreflang="..." /> 表达语言版本对应关系，集合应准确且对称。

pathname / asPath（Router 字段）

pathname 更接近路由模板语义（可能是 /[id]），asPath 更接近用户真实访问路径（可能带参数）。 生成 canonical/alternates 时通常要用归一化后的 asPath。

数据源分层

将路由来源拆成静态/内容/运行时三层，便于合并、降级与定位问题。

URL 规范化

统一尾斜杠、locale 前缀、大小写与 query 规则，避免重复页面与去重不稳定。

CMS（Content Management System）

内容管理系统：本文语境下主要指“内容路由”的来源（例如 Headless CMS/数据库），它决定哪些落地页应该进入 sitemap。

Manifest（路由清单）

把内容系统中的页面聚合成“可访问路由集合”的结果（通常按 slug 聚合 locale），用于驱动 sitemap 与一致性校验。

去重（Dedupe）

在 sitemap 生成阶段避免重复输出同一路径；推荐以规范化后的 pathname 作为去重维度。

语言齐全 gate

生产环境约束：只有当内容页覆盖 requiredLocales 时才进入 sitemap，避免输出会 404 的语言版本。

降级（Degradation）

数据源异常时仍输出最小可用结果，保证 sitemap 永远可抓取（不能 500）。

p50 / p95

分位数：p50 代表“中位数”，p95 代表“较差的 5% 请求”；性能治理通常更关注 p95 的稳定性。

HTML 缓存（Service Layer Cache）

在服务层直接缓存最终 HTML；命中时可跳过整段 SSR，但对缓存键与绕过策略要求更高。

LRU（Least Recently Used）

最近最少使用淘汰策略：缓存容量满时优先淘汰最久未被访问的条目，用于控制内存占用。

LCP（Largest Contentful Paint）

最大内容绘制：用户侧体验指标，反映“页面主要内容什么时候可见”。TTFB 下降往往会帮助 LCP，但仍需以真实用户数据验证。

CLS（Cumulative Layout Shift）

累计布局偏移：用户侧体验指标，反映页面布局稳定性。SSR 缓存不一定直接改善 CLS，但会影响整体体验评估。

Supabase

一个提供数据库、REST API、认证、对象存储等能力的平台。本文把它当作“内容源”（内容表 + Storage）。

Storage bucket

对象存储的桶。本文用“递归枚举 + 下载”的方式把 bucket 内容镜像到本地，保证页面离线也能渲染资源。

routes manifest（routes.json）

路由清单的中间产物：把“可发布内容集合”输出为结构化 JSON，供 sitemap/路由治理复用。

offset/limit 分页

常见分页方式：每次拉取固定数量（limit），通过偏移量（offset）翻页，直到返回条数不足一页。

语言齐全 gate（require all locales）

发布门禁：只有当同一个 slug 覆盖所有必需语言时，才允许进入可发布集合（避免 sitemap/alternates 宣告 404）。

locale mapping

语言码映射：数据库语言码与站点语言码可能不同，需要在“落盘文件名”与“齐全校验”两处同时处理。

软 404（Soft 404）

页面返回 200，但内容形态像“无内容/错误页”。对搜索引擎来说这类页面仍会污染索引与覆盖率。

Crawl budget（抓取预算）

搜索引擎在一段时间内愿意抓取你站点的资源额度。sitemap 宣告大量 404/软 404 会浪费预算并降低抓取效率。