首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >不引一个第三方库:我把 DOCX 和 PDF 导出器自己写了一遍

不引一个第三方库:我把 DOCX 和 PDF 导出器自己写了一遍

原创
作者头像
用户12897604
发布于 2026-11-21 22:36:12
发布于 2026-11-21 22:36:12
270
举报

一个 Electron 桌面端正式文档排版工具的导出通道复盘。 两条通道(DOCX / PDF)全部自研,零第三方运行时依赖,客户内网断网可用。 本文记录的是"自己写"换来的 9 个具体坑,以及最后那道不吃自己报告的验收门槛。


一、为什么不直接用现成的库

一开始我也是想直接装的。放弃的原因有三条,按优先级:

  1. 断网可用。这个工具的典型场景是会议现场、客户内网、封闭机房——装依赖、拉包、跑后装的字体替换,全都可能失败。node_modules 里多一个能联网的东西,就多一处现场翻车的可能。
  2. 产物必须是确定性的。正式文档要"同一份输入,两次导出字节可对齐"。第三方库的默认行为(时间戳、随机 ID、内部排序)经常破坏这一点。
  3. 字体不能被系统替换。这是最硬的一条:正式文档对字体有格式要求,客户机器上没有那个字体时,任何"回退到系统字体"的库行为都是致命的——打印出来的版式和你屏幕上看到的不一样。

所以最终的口径是:ZIP 自己写、OOXML 自己拼、PDF 自己排、字体整档嵌。

代价也很清楚:两条通道源码合计 二十余个源文件、约 230 KB,纯手写 TypeScript,没有一行第三方运行时依赖。


二、DOCX 就是一个 ZIP:第一个坑就在文件名上

DOCX 本质上是一个 ZIP 包。自己写 ZIP,看着简单,坑都在细节:

  • 中文/特殊字符文件名必须打 UTF-8 标志位(通用标志第 11 位)。不打这个位,解压端会按老编码去解,中文路径直接变乱码,Word 报"文件损坏"。
  • 每个条目要写对 CRC32。我用了查表实现(IEEE 802.3 多项式),256 项的静态表在启动时算一次。CRC 写错的表现不是报错,是"能打开但内容截断",极难查。
  • 中央目录必须最后写,且偏移量指回本地头。这意味着写出是两趟:先顺序写本地文件头 + 数据,边写边记录偏移;最后写中央目录和目录结束记录。
  • 压缩不必强求。我们这个通道选了 store(不压缩)。理由:DOCX 是确定性结构化产物,压缩率对本场景不重要,而 store 少一层 inflate/deflate,就少一类"某台机器上解压差异"的可能。读侧则用 node:zlib 的 inflateRawSync,store 条目原样返回。

一句话总结:ZIP 自己写不是难,是容错空间为零——Word 对包结构的容忍度比你想的低得多。


三、OOXML 不是"随便拼的 XML",它是有顺序的

第二类坑更隐蔽。document.xml 里元素的子元素顺序是有 schema 约束的,顺序错了不会有任何警告,Word 直接给你"文件内容有问题,是否恢复"——而恢复后样式全丢。

我踩到的几个典型:

  • w:rPr 里的子元素(字体、字号、加粗、颜色…)必须按 schema 顺序排列,不能按你顺手拼的顺序。
  • w:pPr 里段落属性同理,w:rPr 必须在 w:pPr 的固定位置,不能出现在最后。
  • 表格的 w:tcPr → w:tblBorders、w:insideH/w:insideV 这类属性都有位置约束。
  • w:sectPr(页面设置)必须是 body 的最后一个元素,放中间直接坏。

我的做法是把"顺序"从记忆变成结构:每个元素由一个生成函数负责,函数内部的拼接顺序就是 schema 顺序,不允许调用方自己拼 XML 字符串。这条规则救了很多次——因为一旦允许"顺手加一行",半年后没人记得那行的位置对不对。

另外两件必须提前想清楚的事:

  • 多级列表(numbering.xml)要自己做编号与缩进映射。正式文档的章节号是刚性的,不能用"看起来像列表"的文本框蒙。
  • 目录和页码是"域"(field),不是写死的文字。写死的目录在客户机器上打开永远是旧页码;正确的做法是写域,让 Word 打开时更新。
  • 我们同级标题的编号用了 w:rStyle 加 w:vanish 的隐藏 run 做字节探针——后面第五节会讲,这个"自有机制"反过来成了残留检测的误报源。

四、中文字体:三个槽位,少写一个就回退

这块是正式文档场景独有的坑,也是我花时间最多的地方。

第一,一个字体要在 OOXML 里占三个槽位:w:ascii、w:hAnsi、w:eastAsia。只写 w:ascii,中文部分走 eastAsia 的默认值,英文和数字走 hAnsi 的默认值——结果就是同行中文英文两种字体,看起来像"排版没做完"。我们的样式表里是这么写死的:

w:rFonts w:ascii="..." w:hAnsi="..." w:eastAsia="仿宋_GB2312"

第二,字号单位是"半点"。w:sz 写 24 表示 12 磅。第一次写成 12,导出的文件字号小了一半,肉眼看着"有点不对"但说不上哪里不对——这种坑最耗时间。

第三,字体名必须和客户机器上装的完全一致。仿宋_GB2312 和 仿宋 是两个字体名,差一个字就回退到宋体,版式全变。所以字体族的选择不能靠"差不多就行",要么按格式要求硬指定,要么在导出前做一次字体可用性检查并明确报错——宁可拦住,不要静默替换。


五、PDF:字体整档嵌入,且必须给宽度表

PDF 侧比 DOCX 更硬,因为 PDF 没有"回退"这个概念——字体不在,就是黑块或方框。

我们的选型:

  • Type0 / CIDFontType2 复合字体,Identity-H 编码。中文按 GID 直出,不做 Unicode 直写,避免中文在 PDF 里的老编码问题。
  • FontFile2 整档嵌入,不子集化。子集化能省体积,但会让文件"不可核对":验收时需要从 PDF 字节里反查每页正文,子集化之后字形编号和字符的对应关系被裁剪,反查就不可靠了。这里我们选择用体积换可验证性。
  • 必须写 ToUnicode CMap。否则 PDF 里的中文对阅读器、对复制粘贴、对我们的验收脚本都是"不可读的图形"。我按 bfchar 分段写,每段不超过 100 条——这是实测下来各阅读器都能稳的分段大小。
  • 必须给 /W 宽度数组。这一步最容易漏:不给宽度,PDF 里中文挤成一坨,因为渲染器只能猜每个字形多宽。宽度从字体文件的 unitsPerEm(在 head 表里)换算,比例要按 PDF 的 1000 单位制折算。
  • TTC 要重建为独立 TTF。客户机上常见的是 .ttc 字体集合,直接塞进 FontFile2 会坏——我们先把子字体重建成独立 sfnt 缓冲再嵌。
  • 还有个小工程细节:字体对象组(Type0 / CIDFontType2 / FontDescriptor / FontFile2 / ToUnicode)一共 5 个对象,其中 FontFile2 和 ToUnicode 的内容长度在写出时才知道——所以和 ZIP 一样是两趟写出:先占位,后回填,回填时再 deflate。

六、最后一道门:别信自己的分页器

这条是我认为整个导出通道里最有价值的设计。

分页器是我们自己写的。如果验收也用分页器自己的输出("我算出来第 3 页在这里断的"),那叫自证,不叫验收。

所以我们做了一个反向通道:只读导出后的 PDF 字节,解对象 → 解 ToUnicode CMap → 解内容流 → 还原每一页的文本行,再和预期比对。它不采信分页器自报的任何数字,只认字节里真实存在的东西。

顺带解决了两件事:

  • 结构标记写进 PDF 注释。我在内容流里写了不参与渲染的注释作为结构标记,验收脚本靠它定位页边界,同时不影响 ToUnicode 和阅读器渲染。
  • 图像也算进结构事实。图像 XObject 有没有、在第几页,同样从字节里点,避免"报告说有图、实际没图"。

一句话:验收通道和被验收通道,不能共用同一套假设。


七、比格式更危险的东西:docx 里的残留信息

这是做正式文档才意识到的事:一份"改自上一版"的正式文档,能泄露的东西远不止正文。

我们的残留取证是从 docx 字节读的(不是读内存态),覆盖这几类:

类别

具体位置

泄露什么

修订

w:ins / w:del / w:trackChanges

谁改过、原稿写了什么

批注

w:commentReference + comments.xml

内部讨论原话

隐藏文字

w:vanish 的 run

被"藏起来"但仍在文件里的内容

文档属性

docProps/core.xml 的 dc:creator / cp:lastModifiedBy

上一版文档的作者名

应用属性

docProps/app.xml 的 Company

上一版文档所属的公司名

docProps 这一条最容易被忽略,也最要命:正文删得干干净净,属性里还留着前一家公司的名字和作者,文件一交出去就等于自曝来源。

这里有​个反噬:前面第三节提到的自有编号探针(一段自定义样式的隐藏 run)本身就是"隐藏文字",检测脚本会把自家机制判成残留。所以取证规则里必须有一条排除口径——认得自己的探针,不算残留。

误报也是 bug。一个动不动就报"发现 300 处残留"的工具,用户第三次就不看了。


八、复盘数字

项

实测值

DOCX 侧源码

十余个源文件,合计约 120 KB

PDF 侧源码

十个源文件,合计约 110 KB

第三方运行时依赖

0

全量端到端测试

数十条用例,单轮约 9 分钟

导出方式

两趟写出(占位 → 回填),DOCX 与 PDF 一致

字体策略

DOCX 按槽位指定;PDF 整档嵌入 + ToUnicode + 宽度表


九、Checklist:自研导出通道时该先问自己的 10 个问题

ZIP / 包结构

  • 文件名打过 UTF-8 标志位(bit 11)吗?
  • CRC32 是逐条算对了,还是"能打开就算过"?
  • 中央目录的偏移量是指回本地头,还是拍了个近似值?

OOXML / 格式

  • 元素顺序是"函数负责"还是"谁写谁拼"?
  • 目录和页码写成了域,还是写成了死文字?
  • 多级列表的编号与缩进是自己映射的,还是靠视觉近似?

字体

  • w:ascii / w:hAnsi / w:eastAsia 三个槽位都写了吗?
  • 字号用的是半点单位吗?
  • 字体缺失时是明确报错,还是静默回退?
  • PDF 写了 /W 宽度表和 ToUnicode 吗?用的是整档嵌入还是子集化?(选择前先想清楚"可验证性"值多少体积)

验收

  • 验收读的是导出后的字节,还是分页器自报的数字?
  • 残留扫描认得自己的内部探针吗?(不然误报会毁掉这个功能)

写在最后

自研导出通道不值在"炫技",值在边界清楚:哪一层是格式规范、哪一层是自己的假设,必须拆开。

我的判断标准很简单:如果这个环节出错会让用户在外面丢人(会议现场、客户机房、打印店),那就自己写并自己验;如果是纯展示层,用现成的库更省。

导出通道属于前者。它出错的时候,没有人会给你第二次机会。


本文数字均来自项目实测(文件体积取自 Get-ChildItem,测试时长取自全量 e2e 运行记录)。文中不含产品品牌名与客户信息。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、为什么不直接用现成的库
  • 二、DOCX 就是一个 ZIP:第一个坑就在文件名上
  • 三、OOXML 不是"随便拼的 XML",它是有顺序的
  • 四、中文字体:三个槽位,少写一个就回退
  • 五、PDF:字体整档嵌入,且必须给宽度表
  • 六、最后一道门:别信自己的分页器
  • 七、比格式更危险的东西:docx 里的残留信息
  • 八、复盘数字
  • 九、Checklist:自研导出通道时该先问自己的 10 个问题
  • 写在最后
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档