Word 文档处理方案深度对比：生成、模板与转换

在 Node.js 和前端生态中，处理 Word 文档（.docx）通常面临三个核心需求：从头生成文档、基于模板填充数据、或将文档转换为 Web 可读格式。docx、docxtemplater、mammoth 和 pizzip 分别解决了这些不同层面的问题。理解它们的底层机制和适用边界，对于构建稳定的文档服务至关重要。

🏗️ 核心定位：生成 vs 模板 vs 转换

这四个库的根本区别在于它们对 .docx 文件的“读写”态度不同。

docx 是一个纯粹的生成器。它不关心现有的 .docx 文件，而是通过 JavaScript 对象描述文档结构，然后编译成二进制文件。

// docx: 通过代码定义结构生成新文件
const { Document, Packer, Paragraph, TextRun } = require("docx");

const doc = new Document({
  sections: [{
    properties: {},
    children: [
      new Paragraph({
        children: [new TextRun("Hello World")],
      }),
    ],
  }],
});

const buffer = await Packer.toBuffer(doc);

docxtemplater 是一个模板引擎。它加载一个现有的 .docx 文件，查找其中的占位符（如 {name}），并用数据替换它们。

// docxtemplater: 加载模板并填充数据
const Docxtemplater = require("docxtemplater");
const PizZip = require("pizzip");
const fs = require("fs");

const content = fs.readFileSync("template.docx", "binary");
const zip = new PizZip(content);
const doc = new Docxtemplater(zip, { paragraphLoop: true, linebreaks: true });

doc.render({ name: "John" });
const buffer = doc.getZip().generate({ type: "nodebuffer" });

mammoth 是一个转换器。它读取 .docx 文件，提取内容并转换为 HTML 或文本，不保留复杂的 Word 样式，只保留语义结构。

// mammoth: 转换为 HTML 用于网页展示
const mammoth = require("mammoth");

const result = await mammoth.convertToHtml({ path: "document.docx" });
console.log(result.value); // 输出 HTML 字符串

pizzip 是底层容器处理器。.docx 本质上是 Zip 包，pizzip 负责解压和修改包内的 XML 文件，通常配合 docxtemplater 使用。

// pizzip: 直接操作 Zip 容器（底层）
const PizZip = require("pizzip");
const fs = require("fs");

const content = fs.readFileSync("file.docx", "binary");
const zip = new PizZip(content);

// 直接读取包内的 XML 文件
const xmlContent = zip.file("word/document.xml").asText();

🎨 样式控制：代码定义 vs 模板保留

样式处理是文档库最复杂的部分。docx 要求你在代码中定义样式，而 docxtemplater 继承模板的样式。

docx 需要显式定义样式对象。这给了你最大的灵活性，但代码量较大。

// docx: 代码中定义样式
const { Style, HeadingLevel } = require("docx");

const doc = new Document({
  styles: {
    paragraphStyles: [
      {
        id: "heading1",
        name: "Heading 1",
        basedOn: "Normal",
        next: "Normal",
        quickFormat: true,
        run: { size: 28, bold: true, color: "000000" },
      },
    ],
  },
  sections: [{
    children: [
      new Paragraph({ text: "Title", style: "heading1" })
    ]
  }]
});

docxtemplater 直接使用 Word 中设计好的样式。你只需要在 Word 里设置好字体和颜色，代码只负责填数据。

// docxtemplater: 样式由 template.docx 决定
// Word 模板中：{title} 已经设置为红色加粗

doc.render({ title: "Project Report" });
// 输出文件中，"Project Report" 自动继承模板样式

mammoth 尝试映射样式到 CSS 类，但主要关注内容结构。它不生成 .docx，所以不涉及 Word 样式保留，而是生成 Web 样式。

// mammoth: 样式映射到 CSS
const options = {
  styleMap: [
    "p[style-name='Heading 1'] => h1:fresh",
    "p[style-name='Normal'] => p"
  ]
};

const result = await mammoth.convertToHtml({ path: "doc.docx" }, options);

pizzip 不关心样式。它只处理二进制和 XML 文本。如果你要用它改样式，需要直接操作 word/styles.xml。

// pizzip: 手动修改底层 XML 影响样式（不推荐，极易出错）
const zip = new PizZip(content);
let stylesXml = zip.file("word/styles.xml").asText();
// 需要手动解析并修改 XML 字符串来改变样式定义
stylesXml = stylesXml.replace("<w:val w:val='black'/>", "<w:val w:val='red'/>");
zip.file("word/styles.xml", stylesXml);

🔄 数据循环与逻辑：原生支持 vs 手动实现

处理列表、表格或条件显示是文档生成的常见需求。

docx 通过 JavaScript 数组映射来生成列表。逻辑完全在 JS 控制中。

// docx: 使用 JS 循环生成列表
const items = ["Item 1", "Item 2", "Item 3"];

const doc = new Document({
  sections: [{
    children: items.map(text => new Paragraph({
      children: [new TextRun(text)]
    }))
  }]
});

docxtemplater 支持在 Word 模板中写简单的循环语法（如 {#items}{name}{/items}）。

// docxtemplater: 模板中定义循环逻辑
// Word 模板内容：{#users}{name} - {email}{/users}

doc.render({
  users: [
    { name: "Alice", email: "alice@example.com" },
    { name: "Bob", email: "bob@example.com" }
  ]
});

mammoth 将列表转换为 HTML <ul> 或 <ol>。它只是读取现有结构，不创造新逻辑。

// mammoth: 读取现有列表结构
// 如果 docx 中已有列表，转换为：
// <ul><li>Item 1</li><li>Item 2</li></ul>

pizzip 没有逻辑处理能力。你需要自己解析 XML 中的 w:tr (表格行) 或 w:p (段落) 并复制节点。

// pizzip: 手动复制 XML 节点实现循环（极高复杂度）
// 需要解析 document.xml，找到模板行，克隆节点并替换占位符
// 通常不建议直接使用 pizzip 处理业务逻辑循环

📦 依赖与架构：独立运行 vs 组合使用

架构决策时，依赖链的复杂度是一个重要考量。

docx 是独立的。它不依赖外部 Zip 库来处理生成过程，打包后体积相对可控，API 自包含。

// docx: 独立使用
const { Document, Packer } = require("docx");
// 无需额外配置即可生成文件

docxtemplater 强依赖 Zip 库（如 pizzip）。它本身只处理 XML 模板逻辑，文件读写需要外部模块配合。

// docxtemplater: 必须配合 Zip 库
const Docxtemplater = require("docxtemplater");
const PizZip = require("pizzip"); // 必须引入
// 两者配合才能完成工作

mammoth 是独立的。它内置了解析 .docx Zip 结构的能力，专注于转换逻辑。

// mammoth: 独立使用
const mammoth = require("mammoth");
// 直接传入路径或 Buffer 即可

pizzip 是基础库。它通常不单独出现在业务代码顶层，而是作为 docxtemplater 的底层支撑。

// pizzip: 作为依赖存在
// 通常只在需要自定义 docxtemplater 模块或处理非标准 Zip 操作时直接调用

🌐 实际应用场景推荐

场景 1：动态月度报告生成

数据来自数据库，图表和段落结构每月变化。

• ✅ 最佳选择：docx
• 理由：结构由代码控制，方便根据数据动态增减章节，无需维护 Word 模板文件。

场景 2：批量生成合同或发票

格式固定，法务部门已审核过 Word 模板，只需填入客户信息。

• ✅ 最佳选择：docxtemplater
• 理由：保留法务审核的精确格式，业务人员可在 Word 中调整模板而无需改代码。

场景 3：在线文档预览

用户上传 .docx，系统需要在网页上显示内容。

• ✅ 最佳选择：mammoth
• 理由：将文档转为 HTML，利用浏览器原生渲染，无需后端生成 PDF 或图片。

场景 4：自定义文档加密或水印

需要在底层修改 .docx 包的特定属性或添加隐藏文件。

• ✅ 最佳选择：pizzip (配合其他库)
• 理由：直接操作 Zip 包结构，可以添加非标准部分或修改核心 XML 而不破坏文件完整性。

📊 总结对比表

💡 架构师建议

docx 是构建文档生成服务的基石，适合需要高度动态化的场景，但开发成本较高，因为你需要用代码“画”出文档。

docxtemplater 是业务友好型选择，它将文档设计的权力交还给了非技术人员（通过 Word），适合企业级表单和报告，但需注意模板语法的限制。

mammoth 是展示层的工具，不要试图用它来编辑文档。它在内容迁移和 Web 预览场景中无可替代。

pizzip 是底层齿轮。除非你有非常特殊的底层需求（如自定义模块开发），否则应通过 docxtemplater 间接使用它，避免直接操作 XML 带来的维护噩梦。

最终建议：对于大多数企业应用，组合使用 docxtemplater + pizzip 处理固定格式文档，使用 docx 处理动态报告，使用 mammoth 处理前端预览，是性价比最高的架构方案。