SuperDoc 字体系统完整指南：为什么浏览器里 Word 文档排版总走样，3 种方法快速解决

如果你在浏览器里打开一份 Word 文档（DOCX），发现字体变了、行被拉长、页码对不上——这不是你的错觉。SuperDoc 是一套构建于浏览器的 DOCX 编辑器与 Agent SDK，它的字体系统正是为解决"浏览器里 Word 文档排版走样"这一痛点而设计：通过逻辑字体名到物理字体的智能替换、测量前加载、以及度量兼容（metric-compatible）字体包，让浏览器渲染尽量逼近 Word 桌面版效果。本文将带你快速看懂原理，并给出 3 种立即可用的解决方案。

为什么浏览器里的 Word 文档排版会走样？

先理解问题的根源，才能理解 SuperDoc 为什么这样设计。

DOCX 文件只存字体名，不存字体文件。一份用 Word 打开的文档里，正文可能写着"使用 Calibri 字体"，但 DOCX 包里通常只有这个名字，没有字体本身。于是浏览器渲染时会出现连锁反应：

1. 用户电脑/浏览器没有这个专有字体（如 Calibri、Aptos、Cambria 是微软专有字体）；
2. 浏览器默默换成系统回退字体渲染；
3. 回退字体的字宽（advance）与原字体不同——哪怕每个字符只差 1%，一行文字累积下来就换行位置不同；
4. 行距、页码、表格列宽全部跟着"漂移"——这就是你看到的"排版走样"。

💡关键概念：逻辑字体名 vs 物理渲染字体

SuperDoc 的整个字体系统围绕这两个角色构建（定义见 resolver.ts）：

这样即使浏览器渲染时用了替代字体，导出 DOCX 时依然保留原始字体名，文档意图不丢失。

SuperDoc 字体系统的 4 个核心模块

字体系统代码集中在 shared/font-system/src/，与布局引擎的测量层（fontMetricsCache.ts）协同工作。核心分 4 层：

1️⃣ 字体解析器：为每个文档独立做"字体翻译"

FontResolver 负责把逻辑名翻译成物理字体。每个文档拥有自己独立的一个实例——同一页面上打开两个编辑器，可以各自映射不同的字体而互不干扰。

它按一条优先级阶梯（provider-precedence ladder）决策，从高到低：

替换关系本身不是拍脑袋定的：每一行替换都携带来自上游@docfonts/fallbacks的实测保真度证据（见 substitution-evidence.ts），并标注保真度等级——metric_safe（字宽差 ≤0.5%，行距页码安全）、near_metric（接近精确）、visual_only（字形相似但字宽会重排）。只有通过"资产门"（字体文件确实随包发布）的证据才会真正生效。

2️⃣ 字体注册表：测量之前先把字体加载好

这是解决走样问题最精妙的一环。FontRegistry 实现了"load before measure"（先加载、后测量）策略：

• 注册字体是懒加载的——先登记，不下载；
• 文档进入测量流程前，注册表等待所需字体面真正加载完成（默认 3 秒超时，慢而不卡死）；
• 加载完成的字体才能用于测量和绘制，避免"先用回退字体测量、字体到齐后又重排"的闪烁与错位。

对文档内嵌的字体，SuperDoc 还会解析字体文件的OS/2 表（os2.ts）：判断嵌入许可是否允许网页渲染、并识别它是粗体还是斜体；同时从表头读取天然行高（natural-line-metrics.ts），保证行距计算有据可依。

此外，即使不配置任何字体，SuperDoc 也内置了核心符号回退（core-symbol-fallback.ts）：列表里的•项目符号、数学符号等特殊字符会从专用符号字体取字形，而不是渲染成小方块。

3️⃣ 内置替换包：Calibri → Carlito 的度量兼容方案

@superdoc/fonts（packages/fonts/）是一个可选的开源替代字体包，核心思路是"度量兼容"——用开源字体像素级地复刻微软专有字体的字宽：

字体清单维护在 bundled-manifest.ts，每个字体面都携带许可证信息（OFL、Apache 等）——包内是替代字体，不是微软字体文件本身，所以不覆盖所有字体族，官方文档也诚实地提示"不保证与 Word 渲染完全一致"。

4️⃣ 字体报告：一行 API 看清"每个字体去哪了"

渲染完成后，SuperDoc 生成一份字体报告（构建逻辑见 report.ts），通过superdoc.fonts.getReport()即可拿到，每行包含：

• logicalFamily：DOCX 请求的字体
• physicalFamily：实际渲染的字体
• reason：为什么选它（上表中的 5 种理由）
• loadStatus：字体是否加载成功
• missing：是否已确认"请求的字体没有忠实提供者"

这份报告就是排查走样问题的"仪表盘"，后面验证环节会用到。

3 种解决排版走样的方法（按上手难度排序）

方法一：接入内置替换包（最推荐，两步搞定）

如果你的文档主要使用 Calibri、Times New Roman 这类常见字体，装一个包就够了。安装@superdoc/fonts，把superdocFonts传给编辑器的fonts配置（完整说明见 packages/fonts/README.md 与官方文档 fonts.mdx）：

import { superdocFonts } from '@superdoc/fonts'; new SuperDoc({ selector: '#editor', document: '/sample.docx', fonts: superdocFonts, });

包里的字体 URL 会被 Vite、Webpack 等构建工具自动解析发布，无需手动复制字体文件。如果只想启用部分替换，可以用createSuperDocFonts({ include: ['Calibri', 'Cambria'] })按 Word 字体名精确裁剪。

方法二：自托管正版字体文件（追求 100% 保真）

当文档使用专有字体（如新版 Word 默认的 Aptos）时，替换包帮不上忙——此时应把已获授权的字体文件放到你的站点，并用fonts.families注册每个用到的字面（常规、粗体、斜体、粗斜体要分别注册，一个面不能顶替其他面）。名称与 DOCX 中一致时无需映射，SuperDoc 会在测量前自动加载它们。

方法三：显式映射（字体名不同但有替代方案时）

如果你能提供的字体名和 DOCX 里存的名字不一样（例如想用 Inter 替代 Aptos），用fonts.map显式映射：注册 Inter 的字体文件，再把 DOCX 的字体名映射到它。注意：SuperDoc 会忠实地按映射渲染，但导出时仍写回原始字体名；任意替代字体都可能改变版式，建议只映射你验证过度量的字体。

验证保真度：让"走样"可测量

换字体不是目的，行距和页码不变才是目的。接入字体方案后，建议做 3 步验证：

1. 看报告：调用superdoc.fonts.getReport()，确认每行都有"正向证据"——注册字体loadStatus为loaded，或系统字体systemAvailability为available，且missing为false；
2. 盯保真度：替换类字体的报告行会携带evidence.lineBreakSafe字段，为false表示字宽会重排（例如 Cooper Black → Caprasimo），需要人工复查版式；
3. 对比实测：对同一份文档，在 SuperDoc 和 Word 里分别检查行断点与分页位置，并导出后重新打开，确认原始字体名仍被保留。

📌 跨域提供字体文件时，记得在 Content Security Policy 和 CORS 规则中放行字体所在源。

总结：一张表看懂 SuperDoc 字体系统

浏览器里 Word 文档排版走样的本质，是"字体文件缺失 + 字宽漂移"两个问题。SuperDoc 用"先加载后测量"解决时序问题，用度量兼容替换包和正版字体托管解决字宽问题，再用字体报告让整个链路可观测。掌握以上 3 种方法，你的 DOCX 在浏览器里的排版就能稳稳地"不走样"。