用 Node 的 docx 库自写转换器,把一份含 8 张截图、4 个表格、12 段代码块、4 个提示框的中文 Markdown 使用说明转成排版完整的 Word 文档,全程秒级生成。最痛的坑是竖长截图按固定宽度缩放后超出页面被裁------文中给出完整的 docx 尺寸换算方法与修复方案,另附 Windows 上做验收时 PowerShell 编码、Word COM 卡死、解压工具链的连环坑复盘。
1. 背景与目标
团队内部沉淀了一批 Markdown 格式的工具使用说明(配截图),交付对象是不看 Markdown 的业务同事,需要转成 Word。文档的典型结构:
- 中文正文 + 8~15 张截图(有横屏页面截图,也有手机端竖屏长截图)
- 4 个左右表格(能力清单、命令对照等)
- 多段代码块(安装命令、示例)
- Markdown 引用块
>用作"提示/注意" - 超链接(内部系统入口)
对交付物的要求:
- 图片必须完整嵌入 docx(不能是外链),且不能被页面裁切;
- 有封面标题区、自动目录(TOC)、页眉页脚页码;
- 代码块灰底等宽字体、提示框黄底黄条、表格有表头底色------沿用之前一篇文档已经定稿的视觉规格;
- 转换过程可重复执行:源 md 更新后一条命令重新生成。
约束:Windows 环境,本机装有 Office(Word),无 LibreOffice;文档中大量中文与中文文件名。
2. 技术选型
| 维度 | pandoc | Word COM 脚本 | docx npm 库(自写解析) |
|---|---|---|---|
| 样式控制 | 弱,需 reference.docx 模板,中文字体/提示框/双色页码都要在模板里做 | 强,但每处样式都要 COM API 调用 | 完全可控,样式即代码 |
| 图片处理 | 自动嵌入,但缩放策略难定制 | 可控但繁琐 | 自由:读尺寸、按规则缩放 |
| 目录 TOC | 支持 | 支持 | 支持(域代码) |
| 速度 | 快 | 慢(要起 Word 进程) | 快(纯 Node,秒级) |
| 稳定性 | 高 | 低(无头模式易弹窗/卡死,见坑 4) | 高 |
| 中文支持 | 好,但模板字体配置绕 | 好 | 好(eastAsia 字体显式声明) |
| 可维护/可复用 | 模板二进制,diff 不友好 | 脚本与 Office 版本耦合 | 纯 JS,参数化后多文档复用 |
选型结论:docx npm 库 + 自写轻量 Markdown 解析器。决定性理由是"样式即代码"------视觉规格(灰底代码块、黄条提示框、表头底色、罗马/阿拉伯双段页码)全部落在 JS 里,版本可控、跨文档复用只改三个路径常量;pandoc 的 reference.docx 是黑盒二进制,改一次样式要开 Word 手调;Word COM 的稳定性在无头场景下被实际否决(坑 4)。
顺带引入两个小依赖:image-size 读图片像素尺寸(注意 v2+ 必须 const { imageSize } = require("image-size") 命名导出,默认导出已废弃),图片二进制直接 fs.readFileSync 后塞进 ImageRun。
3. 架构设计
3.1 架构演进
- v1(首篇文档):一次性脚本,图片按"固定显示宽 560px 等比缩放"。当时文档全是横屏截图,没有暴露问题。
- v2 (本文场景):源文档出现 3 张手机竖屏长截图(高宽比 2.2~2.3),固定宽度策略下缩放后高度达 1252~1284px,超过页面可用高度被裁(坑 1)。演进为双约束缩放:宽度上限 560px + 高度上限 820px,先按宽算,超高则按高反算宽。
演进的本质:v1 的图片处理是"一维约束"(只管宽),v2 补成"二维约束"(宽高各自封顶,取更紧的那个)。嵌入图片的排版问题从来不只是宽度问题,页面高度是常被忽略的第二维。
3.2 总体架构
源 md 文件 ──①逐行扫描──▶ parseMd ──▶ blocks[] ──②逐块映射──▶ docx 元素 ──③Packer──▶ .docx
│ │
│ 8 种块类型: │ 每种块一个 buildXxx()
│ heading/para/code/quote/ │
│ image/table/hr/ul/ol │
▼ ▼
parseInline Document 组装
(行内 **粗体**/`代码`/ (双 section + TOC +
[链接](url) → TextRun) 样式表 + numbering)
│
image/ 目录 ◀── imageSize(buf) 读尺寸 ──┘ 图片二进制内嵌
| 组件 | 载体 | 职责 |
|---|---|---|
| 块级解析器 | parseMd(md) |
md 文本 → 类型化 blocks 数组 |
| 内联解析器 | parseInline(text, props) |
单行文本 → TextRun/超链接数组 |
| 渲染器 | buildHeading/buildPara/buildCodeBlock/buildTipBox/buildImage/buildTable/buildListItem/buildHr |
每种 block → docx Paragraph/Table/ImageRun |
| 图片处理 | buildImage(file) + image-size |
读尺寸、双约束缩放、生成图注 |
| 文档组装 | Document({...}) + 两个 section |
样式表、编号、页眉页脚、TOC、分节页码 |
端到端数据流(本次实测):14.6KB md(约 290 行)→ 66 个 blocks → 组装出 108.4KB 的 document.xml,内嵌 8 张 PNG 共约 2.1MB,最终 docx 2.17MB,node convert.js 全程 1 秒内完成,Word 打开统计 15 页。
3.3 块级解析器 parseMd
自写解析器而不引 markdown-it / marked 的决策理由:转换器只消费 8 种块语法(标题/段落/代码块/引用/图片/表格/有序列表/无序列表/分隔线), markdown-it 产出 AST 后仍要再写一层"AST→docx"映射,等于两跳;自写单行正则扫描一跳到位,且渲染规格(比如"引用块渲染成黄底提示框")在解析层就能对齐。代价是 md 方言覆盖面窄------但使用说明类文档语法极其克制,这个代价为零。
逐行状态机 + 三个设计点:
- 表格识别 :先匹配表头行
^\|,再看下一行是否为^\|[-:\s|]+\|$分隔行,两行同时成立才按表格消费,避免把段落里偶然出现的|误判成表格; - 段落合并 :普通行向后贪心合并直到遇到空行或任一块级语法前缀(
#/---/````/>/|/列表/图片),md 的"软换行即空格"语义由paraLines.join(" ")承接; - 行内图片拆分:单独成行的图片走整行匹配;和文字混在一行的图片先用全局正则切出 text/image 交替段,图片段单独成块,文字段按普通段落走------保证"文字+图+文字"的源文档不丢图。
3.4 内联解析器 parseInline
javascript
// 行内语法:**粗体**、`代码`、[文本](url) 三种,其余按纯文本
const regex = /(\*\*([^*]+)\*\*)|(`([^`]+)`)|(\[([^\]]+)\]\(([^)]+)\))/g;
设计点:
- 单遍正则 + 索引推进 :一个分支正则一次扫描捕获三种行内元素,
m.index到last之间的空隙按纯文本 run 输出。比逐字符状态机短一个数量级,且行内语法不允许嵌套,单遍正确; - baseProps 透传 :第二参
baseProps展开进每个TextRun(提示框里传{ color: "6B4E00" },表格表头传{ bold: true }),同一解析器复用到正文/提示框/表格三处而不用写三份; - 超链接走
ExternalHyperlink:URL 单独成为结构化子元素,Word 里可点击、可改样式,而不是把 文本 原样留进正文。
3.5 图片处理:尺寸读取与双约束缩放(v2 核心改动)
docx 的 ImageRun.transformation 单位是像素,内部按 1px = 9525 EMU 换算,所以"页面能放多高"必须先换算成 px 才能和图片缩放比:
| 物理量 | 值 | 换算 |
|---|---|---|
| A4 页面 | 11906 × 16838 twips | 1 inch = 1440 twips = 914400 EMU |
| 左右边距 | 1701 + 1417 twips | 可用宽 8788 twips ≈ 15.5cm ≈ 587px |
| 上下边距 | 1417 × 2 twips | 可用高 14004 twips ≈ 24.7cm ≈ 933px |
也就是说:宽度上限取 560px(14.8cm)留白舒适;高度安全上限约 933px,再扣图注一行 + 段间距,实际取 820px。
javascript
const IMG_DISPLAY_WIDTH = 560; // px
const IMG_MAX_HEIGHT = 820; // px,页面可用高约 933px,留余量给图注
function buildImage(imgFileName) {
const buf = fs.readFileSync(path.join(IMG_DIR, imgFileName));
const dim = imageSize(buf); // 读图片真实像素
const ratio = dim.height / dim.width;
let w = IMG_DISPLAY_WIDTH;
let h = Math.round(w * ratio);
if (h > IMG_MAX_HEIGHT) { // 竖长图:按高度反算宽度
h = IMG_MAX_HEIGHT;
w = Math.round(h / ratio);
}
return [/* ImageRun 段落 + "图 N" 图注段落 */];
}
决策与理由:
- 先按宽、超高再按高:绝大多数图是横屏截图,命中宽度分支一步到位;竖长图命中第二分支后宽度变为 357~367px(约 9.5cm),居中显示视觉上完全可接受------比"整图缩到塞进一页"的等比整体缩小保真度更高;
- 图注"图 N"用独立段落 :自动递增计数,字号 9pt 灰色居中,图片段落与图注段落
spacing互相咬合(图片 after=60,图注 after=160),保证两段不跨页分离的代价是图注跟随图片,可接受; type: "png"必须显式声明 :docx 库 v8+ 要求ImageRun声明媒体类型,不写运行时抛错。
3.6 文档组装:双 section、TOC、页眉页脚
- 双 section 页码 :第 1 节(首页标题区 + 目录)用罗马数字页码
NumberFormat.UPPER_ROMAN,第 2 节(正文)type: SectionType.NEXT_PAGE换新页、阿拉伯页码start: 1重新起算。目录页不算进正文页码,交付观感更正式------这是 Word 文档的常规规范,pandoc 默认做不到; - TOC 用域代码 :
new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })生成目录域,headingStyleRange: "1-3"决定只收录 H1~H3。两个关键配套:- 目录标题本身不能用 HeadingLevel,否则 TOC 会把"目录"自己收录进去;
- 正文生成后页码未定,必须在文档里放一行"右键目录→更新域"的提示(斜体小字),否则读者打开看到的是未刷新的空目录;
- 首页大标题同样不用 HeadingLevel:手动 20pt 加粗居中 + 4.5pt 蓝色底边框做分隔线,避免被 TOC 收录------封面元素与正文标题走两套样式体系;
- 页眉页脚构造器 :
makeHeader()/makeFooter()返回工厂函数而非实例,因为两个 section 各自持有独立 Header/Footer 对象,直接复用同一个实例会被 docx 库拒绝。
3.7 样式渲染细节
| 元素 | 渲染决策 | 理由 |
|---|---|---|
| 代码块 | 每行一个 Paragraph,shading: F0F0F0 灰底 + Consolas + indent: 120 |
逐行 Paragraph 才能让灰底铺满行;空行替换为单空格避免底色断条 |
提示框(> 引用) |
shading: FFF9E6 浅黄底 + border.left 24 号黄条 |
Word 段落左边框即"色条"效果,不需要表格包裹;多行引用先合并为一段 |
| 表格 | 表头行 tableHeader: true + E8EEF7 底色,所有行 cantSplit: true,列宽均分百分比 |
cantSplit 防行内截断跨页;百分比列宽随页面自适应,不需要算绝对 twips |
| 字体 | 正文 ascii: Calibri, eastAsia: Microsoft YaHei,标题 SimHei |
docx 按 ascii/eastAsia 分流:中文字符走 eastAsia 声明,不写会出现宋体回退 |
| 有序列表 | 每个列表独立 numbering reference,LevelFormat.DECIMAL |
复用同一个 reference 会导致不同列表接续编号(1、2、3 → 7、8、9),这是 docx 库 numbering 的默认共享语义 |
4. 关键实现
整个转换器就是一个约 350 行的单文件脚本,结构即 3.2 的架构图,跑法:
bash
npm install docx image-size
node convert.js
# ✅ 已生成: D:\workspace\travel-docs\出差助手使用说明.docx
# 图片: 8 张
配置集中在文件头部的常量区,换文档只改三行:
javascript
const MD_PATH = "D:/workspace/travel-docs/使用说明.md";
const IMG_DIR = "D:/workspace/travel-docs/image";
const OUT_PATH = "D:/workspace/travel-docs/使用说明.docx";
5. 踩坑记录(共 5 个)
坑 1:竖长截图按固定宽度缩放,高度超出页面被 Word 裁掉
现象:转换生成的 docx 里 3 张手机竖屏截图显示不全------底部内容被页边界裁掉,图注也跟着位置错乱。这 3 张图原始尺寸 1240×2772、572×1309、572×1312(高宽比 2.24~2.29),按 560px 宽等比缩放后高度为 1252px、1282px、1284px。
原因 :缩放策略只有宽度一个约束。docx 的 ImageRun.transformation 单位是 px(1px = 9525 EMU),A4 除去上下边距后可用高度只有 14004 twips ≈ 933px;1252px 的图片高度超出可用高度约 34%,Word 对内联图片不会自动缩放,超界部分直接被裁。定位过程就是 3.5 的单位换算表------把"页面高度"和"图片高度"换到同一单位制,数字一对比就清楚了。
解决:
javascript
let w = IMG_DISPLAY_WIDTH;
let h = Math.round(w * ratio);
if (h > IMG_MAX_HEIGHT) { // IMG_MAX_HEIGHT = 820
h = IMG_MAX_HEIGHT;
w = Math.round(h / ratio);
}
竖图改为按高度上限反算宽度(560→约 357~367px),重新生成后 3 张竖图完整显示,图注不再错位。
预防 :嵌入图片前先 imageSize() 算出目标显示高度 ,凡是 displayHeight > 933px(A4 常规边距下的可用高度)就必须走双约束缩放------这条已固化为转换器的常量 IMG_MAX_HEIGHT,并把"px → EMU → 页面 twips"换算表写进脚本注释,后续改页边距时同步校验该常量。
坑 2:PowerShell 5 读无 BOM 的 .ps1,中文路径全变乱码
现象:用脚本生成的 .ps1 调 Word COM 打开 docx,Word 报错弹窗:
很抱歉,找不到您的文件。该项目是否已移动、重命名或删除?
(D:\workspace\鍑哄樊鍔╂墜浣跨敤璇存槑.docx)
文件名"出差助手使用说明"被解成"鍑哄樊鍔╂墜浣跨敤璇存槑"。
原因 :Windows PowerShell 5.1 按系统 ANSI 代码页(中文系统即 GBK)读取无 BOM 的 .ps1 文件;而编辑器/工具写出的 UTF-8 中文被 GBK 强行解码,字节重组成"鍑哄樊..."这类典型乱码。乱码传给 Word COM 自然找不到文件。验证方法:同一文件加 BOM 后 powershell -File 正常识别中文。
解决:二选一,都能绕开 GBK 解码:
bash
# 方式 A:脚本文件加 UTF-8 BOM(\uFEFF 前缀),PS5 见 BOM 即按 UTF-8 解析
node -e "const fs=require('fs');fs.writeFileSync('run.ps1','\uFEFF'+script,'utf8')"
# 方式 B:彻底不落盘,走 -EncodedCommand,传 UTF-16LE 的 base64
powershell -NoProfile -EncodedCommand <base64-of-UTF16LE-script>
预防 :Windows 上生成含中文的 .ps1 一律 UTF-8 带 BOM ;或坚持 -EncodedCommand 管道模式。本地新增检查:生成的 ps1 头两字节必须是 EF BB BF。
坑 3:用 Node 模板字符串生成 PowerShell 脚本,反斜杠转义层级算错
现象 :改用 BOM 方案后仍报错------Test-Path : 路径中有非法字符,报错回显里路径中段变成了不可见字符。
原因 :PowerShell 路径写在 Node 的模板字符串里,C:\\Users\\... 的 \\ 数错一层(模板字符串里 \\ → \,双反斜杠写四层才到两层),变量值里混进裸转义字符,Test-Path 直接抛非法字符。这和坑 2 现象像(都是路径解析失败),但根因完全不同------坑 2 是编码层,坑 3 是转义层。
解决 :不在两种语言之间手拼转义。改成 PowerShell 里路径用单引号原始字符串 + Node 侧 String.raw 生成,或干脆让 Node 只做 base64 编码、脚本本体用文件直传。
预防 :"脚本生成脚本"时,凡是含反斜杠/引号/$ 的跨语言嵌入 ,一律先写死样例做 echo 验证再跑真命令;bash 双引号里 PS 变量的 $ 也会被 bash 吞,这类嵌套调用统一改用文件或 -EncodedCommand 隔离。
坑 4:Word COM 无头模式导出 PDF 卡死
现象 :为做像素级验收,用 Word.Application COM(Visible=$false)打开 docx 后调 ExportAsFixedFormat 导 PDF,命令挂起 150 秒无输出;换 SaveAs2($pdf, 17) 重试,同样卡在 Word 进程不退出,PDF 始终未落盘。
原因:无头 Word 的导出并非完全无人值守------文档首次打开(分页计算 + 图片解码)、COM 调用返回值经管道序列化(CLIXML)等环节都可能阻塞,加上前面坑 2/坑 3 的路径乱码让 Word 实际上没打开目标文档,卡死是复合结果。没有 LibreOffice 的机器上,"docx→PDF→图片"这条验收链路成本极高。
解决 :放弃渲染验收,改走结构验收 :docx 本质是 zip,解开后直接检查 word/document.xml(方法见坑 5),统计出标题 23、表格 4、图片 8、代码块灰底 12、提示框 4、超链接 2,与源 md 的块数逐项对上即判定转换完整。这是可自动化、可复跑的白盒验收。
预防 :Windows 上做 docx 交付验收,优先"解压 docx 校验 document.xml 结构 + 图片数量";确需视觉验收再上 Word COM/LibreOffice,且给 COM 调用一律加超时杀进程兜底(timeout 100 powershell ... + 事后清 WINWORD 进程),不能裸等。
坑 5:Windows 解压工具链的三个扩展名陷阱
现象:结构验收时连环碰壁:
tar -xf tmp_check.docx→tar: This does not look like a tar archive;Expand-Archive -Path tmp_check.docx→.docx 不是支持的存档文件格式。只有 .zip 才是支持的存档文件格式;- 复制成
.zip后Expand-Archive正常解出,word/media/下 8 张 PNG 齐全。
原因 :Windows 自带 bsdtar 对 zip 容器支持残缺(认 .zip 扩展场景有限);Expand-Archive 只按扩展名判断格式 ,内容是标准 zip 但扩展名是 .docx 就拒收。两个工具都把"格式判断"绑死在扩展名上。
解决 :复制为 .zip 再解压:
bash
cp 使用说明.docx tmp_check.zip
powershell -NoProfile -Command "Expand-Archive -Path 'C:\ws\tmp_check.zip' -DestinationPath 'C:\ws\tmp_unzip' -Force"
# 验收:数 media 图片 + grep document.xml 结构
node -e "
const xml = require('fs').readFileSync('tmp_unzip/word/document.xml','utf-8');
const cnt = re => (xml.match(re)||[]).length;
console.log('标题', cnt(/w:val=\"Heading[1-4]\"/g));
console.log('表格', cnt(/<w:tbl[ >]/g));
console.log('图片', cnt(/<w:drawing/g));"
预防 :把"docx → 复制 .zip → Expand-Archive → 查 document.xml"封装成一条验收命令进交付流程;给团队机器装 7-Zip 一劳永逸(7z x xxx.docx 不看扩展名)。
6. 总结
成果:约 350 行的 Node 单文件转换器,把 14.6KB 中文 md(8 图 4 表 12 代码块 4 提示框)转成 2.17MB、15 页的成品 docx,生成耗时 1 秒内;已复用于两篇不同文档,换文档只改三个路径常量。结构验收(解压 + document.xml 统计)8 图 8/8、4 表 4/4、23 标题全对上。
经验教训集中在两点:一是嵌入图片要看二维 ------宽度只是显性约束,页面高度(px 换算后约 933px)才是竖长截图的隐形天花板,双约束缩放一行判断解决;二是 Windows 上的自动化验收链路比转换本身难------PowerShell 5 的 GBK 默认解码、无 BOM 乱码、跨语言转义、Word COM 无头卡死、Expand-Archive 扩展名死板,五个坑里四个出在验收而非转换。结构验收(白盒查 XML)代替渲染验收(像素比对)是在这个环境里性价比最高的折中。
后续计划:把 IMG_MAX_HEIGHT 按页边距动态计算而不是写死 820;转换器抽成 npm 小工具(md2docx-cn)支持命令行传参与 YAML 样式覆盖。
参考
- docx (npm) 官方文档:https://docx.js.org/
- image-size (npm):https://www.npmjs.com/package/image-size
- OOXML 尺寸单位 EMU/twips 换算:ECMA-376 规范