【Node.js】Markdown 转带图片 Word 文档实战:docx 库转换器设计与 5 个踩坑

用 Node 的 docx 库自写转换器,把一份含 8 张截图、4 个表格、12 段代码块、4 个提示框的中文 Markdown 使用说明转成排版完整的 Word 文档,全程秒级生成。最痛的坑是竖长截图按固定宽度缩放后超出页面被裁------文中给出完整的 docx 尺寸换算方法与修复方案,另附 Windows 上做验收时 PowerShell 编码、Word COM 卡死、解压工具链的连环坑复盘。

1. 背景与目标

团队内部沉淀了一批 Markdown 格式的工具使用说明(配截图),交付对象是不看 Markdown 的业务同事,需要转成 Word。文档的典型结构:

  • 中文正文 + 8~15 张截图(有横屏页面截图,也有手机端竖屏长截图)
  • 4 个左右表格(能力清单、命令对照等)
  • 多段代码块(安装命令、示例)
  • Markdown 引用块 > 用作"提示/注意"
  • 超链接(内部系统入口)

对交付物的要求:

  1. 图片必须完整嵌入 docx(不能是外链),且不能被页面裁切;
  2. 有封面标题区、自动目录(TOC)、页眉页脚页码;
  3. 代码块灰底等宽字体、提示框黄底黄条、表格有表头底色------沿用之前一篇文档已经定稿的视觉规格;
  4. 转换过程可重复执行:源 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 方言覆盖面窄------但使用说明类文档语法极其克制,这个代价为零。

逐行状态机 + 三个设计点:

  1. 表格识别 :先匹配表头行 ^\|,再看下一行是否为 ^\|[-:\s|]+\|$ 分隔行,两行同时成立才按表格消费,避免把段落里偶然出现的 | 误判成表格;
  2. 段落合并 :普通行向后贪心合并直到遇到空行或任一块级语法前缀(#/---/`` `` />/|/列表/图片),md 的"软换行即空格"语义由 paraLines.join(" ") 承接;
  3. 行内图片拆分:单独成行的图片走整行匹配;和文字混在一行的图片先用全局正则切出 text/image 交替段,图片段单独成块,文字段按普通段落走------保证"文字+图+文字"的源文档不丢图。

3.4 内联解析器 parseInline

javascript 复制代码
// 行内语法:**粗体**、`代码`、[文本](url) 三种,其余按纯文本
const regex = /(\*\*([^*]+)\*\*)|(`([^`]+)`)|(\[([^\]]+)\]\(([^)]+)\))/g;

设计点:

  1. 单遍正则 + 索引推进 :一个分支正则一次扫描捕获三种行内元素,m.index 到 last 之间的空隙按纯文本 run 输出。比逐字符状态机短一个数量级,且行内语法不允许嵌套,单遍正确;
  2. baseProps 透传 :第二参 baseProps 展开进每个 TextRun(提示框里传 { color: "6B4E00" },表格表头传 { bold: true }),同一解析器复用到正文/提示框/表格三处而不用写三份;
  3. 超链接走 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 解压工具链的三个扩展名陷阱

现象:结构验收时连环碰壁:

  1. tar -xf tmp_check.docx → tar: This does not look like a tar archive;
  2. Expand-Archive -Path tmp_check.docx → .docx 不是支持的存档文件格式。只有 .zip 才是支持的存档文件格式;
  3. 复制成 .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 样式覆盖。

参考

相关推荐
思特奇时空智能23 分钟前
大规模点要素地图渲染性能优化实践
vue.js·arcgis·性能优化·node.js·html·gis·webgl
w3296362712 天前
飞书接单到月度结算:我用一个 DSH 插件跑通鞋类采购 WMS,附 22 项验收
pdf·node.js·飞书·后端开发·ai agent
濮水大叔3 天前
Cabloy/Vona 为什么不需要 NestJS 的 Dynamic Module
typescript·node.js·nestjs
匠云创新3 天前
读完一万段要两分钟:我们把标书读取从 WPS 对象模型搬到了 docx 解析
性能优化·node.js
FungLeo3 天前
成为全栈·Vue 管理后台篇·编辑器图片上传:从文件选择到文章附件关联
前端·vue.js·编辑器·markdown·文件上传·formdata·附件管理
某哈压力大3 天前
SSH 突然 Connection reset?不是密钥坏了,是 OpenSSL 把 sshd 干趴了
前端·node.js·命令行
回眸&啤酒鸭3 天前
【回眸】Node.js 新手从零到一实战指南
node.js
浪遏3 天前
recruitment-cli:让 AI 接手求职招聘,从架构到一次发送超时
架构·typescript·node.js
沉默小管5 天前
我用 NestJS + Nuxt 3 做了个导航站,聊几个踩过的坑
node.js·seo