企业官网建设流程全解析

• 前端
• CLI
• 开发工具

本文以 Fontsource 注册表中 Crimson Pro 字体家族的英文描述文件 为核心，先还原这份描述所讲的 Garalde 衬线字体家族的历史与设计定位，再结合仓库源码追踪该文件从上游仓库抓取、Zod 模式校验、打包进注册表快照，直至被 API 与网站消费的完整生命周期。读完后你能理解 Fontsource 注册表里一个字体家族目录（family.json、distribution.json、description.en-US.md、license.txt）各自承担什么职责，以及描述文件如何最终出现在字体详情页与 API 响应中。

描述文件原文：Crimson Pro 是谁

描述文件位于 registry/data/families/google/crimson-pro/description.en-US.md，文件名中的en-US表明它是按地区/语言维度组织的本地化内容。原文共五段，内容如下：

Crimson Pro is a serif typeface family: Contemporary, clear, classic and rounded/open. Something for a college textbook, editorial websites and any reading experience with book-length texts. It contributes to the tradition of beautiful Garamond-inspired typefaces, often called "Garalde" or "Old Style," and has 8 named weights, in Roman and Italic, and is available as a Variable Font with a Weight axis. The first Crimson design was initiated by Sebastian Kosch in 2009, and he later completely redrew a new version called Crimson Prime. Google commissioned Jacques Le Bailly to review both typefaces, and develop Crimson Pro as a new design that synthesises both designs into a final authoritative family, first released in January 2019. All decisions were made to enable better readability for longer texts and the ability to make good and diverse typography. The Crimson Pro project is led by Jacques Le Bailly, a type designer based in Den Haag, Netherlands. To contribute, see github.com/Fonthausen/CrimsonPro

从中可以提取出以下关键事实，它们与同目录下的结构化数据可以互相印证：

• 设计血统：Crimson Pro 属于 Garamond 一脉的 "Garalde"/"Old Style"（老式）衬线字体，风格关键词是 Contemporary（当代）、clear（清晰）、classic（经典）、rounded/open（圆润/开阔），定位为大学教材、编辑类网站等长文本阅读场景。
• 字重结构：提供 8 个命名字重，Roman（正体）与 Italic（斜体）齐备，并以带 Weight（wght）轴的 Variable Font 形式发布。
• 历史脉络：最早的 Crimson 设计由 Sebastian Kosch 于 2009 年启动，其后他彻底重绘出 Crimson Prime；Google 委托 Jacques Le Bailly 审视两个版本，并将其合成为最终的权威家族 Crimson Pro，2019 年 1 月首次发布。所有设计决策都围绕长文本可读性与多样排版能力。
• 项目归属：项目由荷兰 Den Haag 的字型设计师 Jacques Le Bailly 主导，上游项目维护在 Fonthausen/CrimsonPro 仓库（该 URL 同时记录在 family.json 的project.repository字段中）。

家族元数据：family.json 中的结构化事实

描述文件旁边是同一目录下的 family.json，它以结构化字段承载了描述文本之外的全部可校验事实：

几个值得展开的细节：

标签的来龙去脉。serif/old-style-garalde这类分组/标签形式的 tag ID 在全局分类文件 taxonomy.json 中有对应的展示标签定义；模式层则要求 tag ID 形如group/tag（见 schema.ts 中的tagIdSchema与taxonomySchema），并强制serif、sans-serif、slab-serif三者至多出现其一，避免分类冲突。

来源溯源（provenance）。provenance字段声明该字体来自google/fonts仓库的ofl/crimsonpro目录，并锁定了一个 40 位十六进制 revision；project字段则指向作者自维护的上游项目仓库及 revision。这种"双锚点"设计让每个字体家族都可以精确回溯到上游快照，family.json中的路径、sha256 字段在 schema.ts 的familySchema中都有严格的正则与结构约束。

源文件检查（inspection）。sources数组声明了两个变量源文件CrimsonPro[wght].ttf（正体，约 240 KB）与CrimsonPro-Italic[wght].ttf（斜体，约 247 KB），每个文件附带 sha256 与检查数据：

• wght轴范围min: 200 / default: 400 / max: 900—— 正是描述文件所说 "8 named weights + Weight 轴" 的机器可读版本；
• glyphs: 832、codepoints: 689、outline: "glyf"、fontVersion: "Version 1.003"；
• OpenType 特性：gsub含aalt、case、ccmp、dlig、frac、liga、lnum、onum、pnum、tnum、ordn、sups、subs等 18 项，gpos含kern、mark、mkmk，说明该字体支持上下标、分数、等宽/旧式数字等高级排版能力；
• unicodeRange覆盖基本拉丁文、拉丁文扩展 A/B、越南文、货币符号与数学符号等区间。

languages数组列出了约 488 个以拉丁字母书写的语言 ID（如en_Latn、fr_Latn、vi_Latn），这是"语义语言覆盖"清单，与后文distribution.json中面向打包的字符子集是两个不同维度的概念。

分发声明：distribution.json 定义了可安装的包形态

distribution.json 决定这个家族对外分发成哪些包与文件：

{ "characters": { "defaultSubset": "latin", "subsets": [ { "definition": "latin", "id": "latin" }, { "definition": "latin-ext", "id": "latin-ext" }, { "definition": "vietnamese", "id": "vietnamese" } ] }, "static": [ { "style": "italic", "weight": 200 }, { "style": "normal", "weight": 200 }, "...（200–900 共 8 个字重 × normal/italic，合计 16 个静态面）" ], "variable": [ { "axisKey": "wght", "style": "italic" }, { "axisKey": "wght", "style": "normal" } ] }

对照描述文件可以发现完全的一致性：static的 16 个条目恰好是"8 named weights, in Roman and Italic"；variable的两个wght条目对应CrimsonPro[wght].ttf与CrimsonPro-Italic[wght].ttf两个源文件。defaultSubset为latin，意味着默认导入与默认预览都落在latin子集上。该结构的合法约束由 schema.ts 中的familyDistributionSchema保证：static与variable至少声明其一，characters要么是"all"，要么携带defaultSubset与至少一个子集定义。

描述文件的生成与校验：源码证据

description.en-US.md并非手写的孤立文件，而是注册表流水线中的一个受控产物。从源码结构看，它的生命周期如下：

1. 从上游 HTML 转换而来。registry/scripts/google.ts 中存在文件名映射['DESCRIPTION.en_us.html', 'description.en-US.md']：抓取google/fonts上游时，字体目录里的DESCRIPTION.en_us.html被提取并规范化为 Markdown 描述文件，落到registry/data/families/google/<id>/下。

2. 属于字体家族目录的固定文档集合。registry/scripts/font-files.ts 明确列出文档白名单DOCUMENTS = ['article.en-US.md', 'description.en-US.md']，描述文件与可选的长文article.en-US.md一并参与分发归档。

**3. 注册表级校验。 **registry/scripts/validator.ts 在validateRegistry中为每个家族目录只允许family.json、icons.json、license.txt、distribution.json、description.en-US.md、article.en-US.md六类文件存在，目录中任何未列出的文件都会触发 "Unlisted or unsupported registry file" 断言失败。也就是说，Crimson Pro 目录下这四个文件（描述、家族元数据、分发声明、许可证文本）的构成本身就是被强校验的契约。

4. 内容安全清洗。由于描述文本最终会进入 API 响应与网页渲染，测试用例（见 registry/scripts/registry.test.ts）会断言生成的description.en-US.md不包含javascript:伪协议与alert(1)等脚本片段，同时保留合法的 Markdown 链接（[safe](https://example.com/info)），即上游 HTML 在转换为 Markdown 时经过了消毒处理。

5. 许可证并列存放。同目录的 license.txt 保存完整的 OFL 1.1 文本，family.json中则只留license.id、URL 与版权署名（Copyright 2018 The Crimson Pro Project Authors），完整文本在打包阶段注入，避免每个家族元数据重复携带长文本。

消费链路：从注册表目录到 API 响应

描述文件被读取并注入公共视图的代码位于 registry/scripts/archive.ts：

const [description, article, licenseText] = await Promise.all([ readTextIfExists(join(directory, 'description.en-US.md')), readTextIfExists(join(directory, 'article.en-US.md')), readFile(join(directory, 'license.txt'), 'utf8'), ]);

随后在构建families/{id}.json注册表视图时（archive.ts），三者被组装为按语言索引的content字段与完整license.text：

{ "id": "crimson-pro", "family": "Crimson Pro", "classifications": ["serif"], "tags": ["serif/old-style-garalde"], "designer": "Jacques Le Bailly", "license": { "id": "OFL-1.1", "attribution": "..." , "text": "（完整 OFL 文本）" }, "content": { "en-US": { "description": "Crimson Pro is a serif typeface family: ..." } }, "sources": [ "...", "..."], "distribution": { "...": "..." } }

这一视图的响应结构由 api/shared/registry.ts 中的LocalizedContentSchema约束：description被显式描述为 "Markdown family description"，article为 "Markdown family article"，均为可选的 Markdown 字符串；外层content是语言代码 -> LocalizedContent的记录。API 侧由 api/worker/src/routes/registry.ts 的 Registry 路由暴露（getRegistryView读取families/{id}.json等视图文件），响应头附带X-Registry-Revision标明所解析的注册表快照版本。此外，仓库文档 website/docs/api/font-id.mdx 中还记载了面向单字体的/v1/fonts/{id}端点（响应含id、family、subsets、weights、variants等字段），供程序化查询单个字体家族使用。

在实际项目中使用 Crimson Pro

描述文件谈的是"为什么选它"，注册表数据谈的是"怎么用它"。基于 website/docs/getting-started/install.mdx 的通用安装方式，Crimson Pro 的使用路径是：

优先使用变量包（distribution.json声明了wght轴，200–900 连续可调）：

npm install @fontsource-variable/crimson-pro

// 在应用入口文件导入一次 import "@fontsource-variable/crimson-pro";

生成的 CSS 使用unicode-range，浏览器只会下载页面实际用到的字符集；按 distribution.json 的声明，latin是默认子集，通常无需手动挑选。

静态包用于需要固定字面的场景（对应static中的 16 个字面）：

import "@fontsource/crimson-pro"; // 默认字重 400 import "@fontsource/crimson-pro/200.css"; // 最细字重 import "@fontsource/crimson-pro/900-italic.css"; // 最重斜体

注意同字重的正体与斜体是两个独立导入：900.css不包含斜体，需要900-italic.css另行导入。需要大量字重时，官方文档建议改回变量包以减少文件数量。

导入之后在样式表中按家族名引用即可：

body { font-family: "Crimson Pro", serif; }

如果需要连续字重之外的斜体变量面，则对应variable数组中的wght+italic条目（导入wght轴斜体变体），这与描述文件中 "Roman and Italic … Variable Font with a Weight axis" 的声明一一对应。

小结

registry/data/families/google/crimson-pro/description.en-US.md 看似只是一段字体介绍文字，实际它是 Fontsource 注册表数据契约的一环：

1. 内容上，它交代了 Crimson Pro 的 Garalde 血统、2009 年至今的设计演进与 8 字重 +wght轴的结构；
2. 数据上，它必须与 family.json、distribution.json、license.txt 共同构成通过白名单校验的家族目录；
3. 链路上，它由上游DESCRIPTION.en_us.html转换而来，经消毒后由 archive.ts 注入content["en-US"]，最终通过 api/shared/registry.ts 的LocalizedContentSchema约束进入 API 与网站字体详情页。

理解了这条链路，就能把注册表中任何一个字体家族的描述文件，映射到其上游来源、校验规则、API 形态与 npm 包用法。

• 前端
• CLI
• 开发工具