一个 Electron 桌面端正式文档排版工具的导出通道复盘。 两条通道(DOCX / PDF)全部自研,零第三方运行时依赖,客户内网断网可用。 本文记录的是"自己写"换来的 9 个具体坑,以及最后那道不吃自己报告的验收门槛。
一开始我也是想直接装的。放弃的原因有三条,按优先级:
node_modules 里多一个能联网的东西,就多一处现场翻车的可能。所以最终的口径是:ZIP 自己写、OOXML 自己拼、PDF 自己排、字体整档嵌。
代价也很清楚:两条通道源码合计 二十余个源文件、约 230 KB,纯手写 TypeScript,没有一行第三方运行时依赖。
DOCX 本质上是一个 ZIP 包。自己写 ZIP,看着简单,坑都在细节:
node:zlib 的 inflateRawSync,store 条目原样返回。一句话总结:ZIP 自己写不是难,是容错空间为零——Word 对包结构的容忍度比你想的低得多。
第二类坑更隐蔽。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)要自己做编号与缩进映射。正式文档的章节号是刚性的,不能用"看起来像列表"的文本框蒙。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 侧比 DOCX 更硬,因为 PDF 没有"回退"这个概念——字体不在,就是黑块或方框。
我们的选型:
bfchar 分段写,每段不超过 100 条——这是实测下来各阅读器都能稳的分段大小。/W 宽度数组。这一步最容易漏:不给宽度,PDF 里中文挤成一坨,因为渲染器只能猜每个字形多宽。宽度从字体文件的 unitsPerEm(在 head 表里)换算,比例要按 PDF 的 1000 单位制折算。.ttc 字体集合,直接塞进 FontFile2 会坏——我们先把子字体重建成独立 sfnt 缓冲再嵌。FontFile2 和 ToUnicode 的内容长度在写出时才知道——所以和 ZIP 一样是两趟写出:先占位,后回填,回填时再 deflate。这条是我认为整个导出通道里最有价值的设计。
分页器是我们自己写的。如果验收也用分页器自己的输出("我算出来第 3 页在这里断的"),那叫自证,不叫验收。
所以我们做了一个反向通道:只读导出后的 PDF 字节,解对象 → 解 ToUnicode CMap → 解内容流 → 还原每一页的文本行,再和预期比对。它不采信分页器自报的任何数字,只认字节里真实存在的东西。
顺带解决了两件事:
一句话:验收通道和被验收通道,不能共用同一套假设。
这是做正式文档才意识到的事:一份"改自上一版"的正式文档,能泄露的东西远不止正文。
我们的残留取证是从 docx 字节读的(不是读内存态),覆盖这几类:
类别 | 具体位置 | 泄露什么 |
|---|---|---|
修订 |
| 谁改过、原稿写了什么 |
批注 |
| 内部讨论原话 |
隐藏文字 |
| 被"藏起来"但仍在文件里的内容 |
文档属性 |
| 上一版文档的作者名 |
应用属性 |
| 上一版文档所属的公司名 |
docProps 这一条最容易被忽略,也最要命:正文删得干干净净,属性里还留着前一家公司的名字和作者,文件一交出去就等于自曝来源。
这里有个反噬:前面第三节提到的自有编号探针(一段自定义样式的隐藏 run)本身就是"隐藏文字",检测脚本会把自家机制判成残留。所以取证规则里必须有一条排除口径——认得自己的探针,不算残留。
误报也是 bug。一个动不动就报"发现 300 处残留"的工具,用户第三次就不看了。
项 | 实测值 |
|---|---|
DOCX 侧源码 | 十余个源文件,合计约 120 KB |
PDF 侧源码 | 十个源文件,合计约 110 KB |
第三方运行时依赖 | 0 |
全量端到端测试 | 数十条用例,单轮约 9 分钟 |
导出方式 | 两趟写出(占位 → 回填),DOCX 与 PDF 一致 |
字体策略 | DOCX 按槽位指定;PDF 整档嵌入 + ToUnicode + 宽度表 |
ZIP / 包结构
OOXML / 格式
字体
w:ascii / w:hAnsi / w:eastAsia 三个槽位都写了吗?/W 宽度表和 ToUnicode 吗?用的是整档嵌入还是子集化?(选择前先想清楚"可验证性"值多少体积)验收
自研导出通道不值在"炫技",值在边界清楚:哪一层是格式规范、哪一层是自己的假设,必须拆开。
我的判断标准很简单:如果这个环节出错会让用户在外面丢人(会议现场、客户机房、打印店),那就自己写并自己验;如果是纯展示层,用现成的库更省。
导出通道属于前者。它出错的时候,没有人会给你第二次机会。
本文数字均来自项目实测(文件体积取自 Get-ChildItem,测试时长取自全量 e2e 运行记录)。文中不含产品品牌名与客户信息。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。