React-PDF 与 Web 预览「像素级」对齐实践

摘要

用 @react-pdf/renderer 做在线简历时，常见痛点是：浏览器里看的和导出的 PDF 不是同一套布局。本文结合一类简历编辑器实践，说明如何用同一套文档组件、统一的 px→pt 换算和可控的正文字号档位，让预览与导出尽量一致，并顺带说明列表缩略图与 PDF 同源的思路。

网站链接：https://beautyresume.com

1. 为什么很难「完全一致」

• 渲染引擎不同：DOM + CSS 与 React-PDF 的 Yoga/Flex 布局、字体子集、换行规则都有细微差别。
• 单位不同：网页习惯 px，React-PDF 的 fontSize 常用 pt（点）。若混用或凭感觉写死，两端的字号阶梯会对不上。
• 预览方式不同：若预览用 HTML 套壳、导出用另一套模板，漂移是必然的。

结论：不要追求「和任意网页截图逐像素相同」，而应追求**「预览与导出共用同一棵 PDF 文档树 + 同一套字号体系」**，把差异收敛到可接受范围。

2. 同一数据源、同一 ResumeDocument

编辑器里右侧（或分栏）预览应直接渲染与 pdf() 导出相同的 ResumeDocument（及模板子组件），Redux（或等价状态）里只维护一份 ResumeData。

这样改模块顺序、主题色、正文字号时，预览与下载走同一套 props，避免「改 A 忘改 B」。

3. px 与 pt 的显式换算（对齐字号阶梯）

在样式模块中约定：正文用「CSS px 语义」的配置值，再统一换算为 PDF 的 pt：

• 行业常用换算：96 CSS px = 1 inch = 72 pt，即 pt = px * 72/96。
• 由「正文 px」推导「区块标题 / 页内大标题」等档位（例如正文 +4px、+10px 再换算），保证整页层级比例固定。
• 用户从设置面板选的 pdfBodyPx 应用 clamp 限制在最小～最大合法区间，并 round，避免 localStorage 脏数据导致布局抖动。

这样**配置面板上的「14px 默认」**与 PDF 引擎里的 pt 有唯一对应关系，而不是两处各写一套魔法数字。

4. 预览组件：仍然看「真 PDF」

除 React-PDF 自带的预览方式外，常见还会用 react-pdf（pdf.js）在浏览器里渲染 Blob。要点：

• worker 路径必须指向打包后的 pdf.worker 资源，否则大文件预览不稳定。
• 列表「封面图」若需要：可先 pdf() 生成与线上一致的 Blob，再用 pdf.js 渲染第一页到 Canvas，导出 PNG 上传对象存储；这样缩略图与真实 PDF 第一页同源，避免「列表一张图、点开另一套版式」。

5. 仍会对不齐的情况（预期管理）

• 自定义字体加载时机、字距微调、极端长单词/URL 断行。
• 用户操作系统字体回退链不同。