指南 · 专家
版本基线 3.x。深入边界与权衡：免费 vs 付费模块全表、open-core 授权（MIT/GPLv3）含义、Word「拆标签」经典坑、raw XML 的限制、与
docx/ SheetJS 的选型。
一、免费边界：算清这条线
docxtemplater 是 open core（开放核心）——这是用它前必须算清的一件事。
免费核心 + 免费 expressions 解析器能做：
- 占位符替换
{name} - 循环
{#}{/}与反向条件{^}{/} - 表格行循环（标签放进表格行）
- raw XML
{@}（段落级） - 自定义分隔符、
nullGetter - 点号嵌套、运算、比较、三元、过滤器、
$index、赋值（expressions 解析器）
付费商业模块（约 19 个，需买 license）：
| 模块 | 解决的事 |
|---|---|
| image | 往文档里插入图片 |
| html | 把 HTML 作为富文本插入 |
| chart | 把数据绑定进原生图表 |
| xlsx | 操作 Excel 单元格 |
| slides | PPT 幻灯片复制/拆分 |
| table | 复杂表格（跨行合并/嵌套） |
| styling | 动态样式 |
| footnotes | 脚注 |
| subtemplate | 子模板嵌入 |
| error-location | 错误在模板中的精确定位 |
经验法则：纯文本 + 表格行 + 条件 + 表达式的报表/合同 → 免费搞定；一旦要插图片 / 插 HTML / 画图表 / 写 xlsx 单元格 → 需对应付费模块。
二、授权：MIT 还是 GPLv3
核心库是 MIT / GPLv3 双许可（dual licensed）：
- 选 MIT：可闭源商用，最宽松（多数项目走这条）。
- 选 GPLv3：免费，但有 copyleft 传染性约束。
双许可意味着你可以按 MIT 闭源商用核心库，不必开源自己的代码。付费的是功能模块与商业支持，不是核心本身。
三、Word「拆标签」经典坑
最常见的疑难：一个明明写对的 {tag}，render 却报 unopened/unclosed tag。
根因：在 Word 里编辑时，拼写检查、格式变化（哪怕只是光标经过）会把一个标签在底层 OOXML 里拆进多个 <w:r>（run），变成类似 {ta}{g}，docxtemplater 就识别不到完整标签。
应对：
- 把标签一次性输入完，中途别改格式。
- 选中标签处清除格式（或重打一遍）。
- 用纯文本方式粘贴标签，避免携带格式。
- 用官方/社区工具检查模板里的标签完整性。
四、raw XML 的限制
免费的 {@rawXml} 很有用，但有明确边界：
- 它主要在段落级工作，适合插入一段段落级的原始 OOXML。
- 不能用它插入图片、复杂表格等需要专门处理（多部件、关系引用）的元素——那是 image/table 等付费模块的事。
- 它不转义内容（这正是「raw」的含义），插入非法 XML 会破坏文档。
五、性能与稳健
- 模板预编译复用：同一模板渲染多份时，读文件 +
new PizZip的开销可考虑复用；但 docxtemplater 实例渲染后状态会变，通常每份新建实例更稳妥。 - 异步数据并发：
renderAsync会并行 resolve 数据里的多个 Promise，适合批量拉取图片/远程值。 - 错误兜底：生产环境务必 try/catch 并遍历
error.properties.errors，把模板错误转成对用户友好的提示，而不是把 MultiError 直接抛给前端。
六、选型：docxtemplater vs docx vs SheetJS
| 维度 | docxtemplater | docx（dolanmiu） | SheetJS / ExcelJS |
|---|---|---|---|
| 范式 | 模板填充 | 编程式构造 | 表格读写 |
| 样式来源 | 模板（Office 里排版） | 代码 | 数据/代码 |
| 适合 | 已有精美模板、只缺数据 | 完全代码生成 Word | 电子表格数据 |
| 非程序员可维护模板 | 可 | 否 | — |
| 关键能力收费 | 部分模块付费 | 免费 | SheetJS 样式需 Pro |
怎么选：
- 有设计好的 Word/PPT 模板、只想填后端数据 → docxtemplater（最佳场景）。
- 要用代码从零拼复杂 Word 结构、不想做模板 → docx。
- 主要是电子表格数据读写 → SheetJS / ExcelJS（见同区笔记）。
七、免费边界再强调
最后回到那条贯穿全篇的红线：核心免费、功能模块付费。
立项时先列清楚要用到哪些能力：若出现「插图片 / 插 HTML / 画图表 / 写 xlsx 单元格 / 子模板」，就要把对应付费模块的 license 成本算进预算；否则免费核心 + expressions 解析器足矣。