docx vs html-docx-js vs mammoth：文档生成与解析的架构抉择

在 Web 应用中处理 Word 文档通常涉及两个相反的方向：生成（写入）和解析（读取）。docx 和 html-docx-js 属于生成工具，而 mammoth 是解析工具。这种根本性的差异决定了它们在不同架构场景下的位置。让我们深入对比它们的技术实现和适用边界。

🔄 数据流向：生成 vs 读取

docx 是一个完整的文档生成引擎。

• 它通过构建 OOXML 对象树来创建文件。
• 适合从零开始构建结构化文档。

// docx: 生成文档
import { Document, Packer, Paragraph } from "docx";

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

const blob = await Packer.toBlob(doc);

html-docx-js 是一个 HTML 到 Word 的转换器。

• 它将 HTML 字符串包装成 Word 可识别的格式。
• 适合将网页内容直接导出。

// html-docx-js: 转换 HTML 为文档
import htmlDocx from 'html-docx-js';

const htmlContent = '<h1>Hello World</h1>';
const blob = htmlDocx.asBlob(htmlContent);
// 直接返回 Blob，无需构建对象树

mammoth 是一个文档读取器。

• 它不能生成文档，只能解析现有文件。
• 适合处理用户上传的文件。

// mammoth: 读取文档
import mammoth from "mammoth";

// 必须传入 ArrayBuffer 或 Buffer
const result = await mammoth.convertToHtml({ arrayBuffer: buffer });
const html = result.value; // 输出 HTML 字符串

🎨 样式控制粒度：精确布局 vs 快速映射

docx 提供像素级的样式控制。

• 你可以定义页边距、页眉、页脚、表格边框。
• 样式与内容分离，类似 CSS 但针对 Word。

// docx: 精确控制样式
import { TextRun, HeadingLevel } from "docx";

const paragraph = new Paragraph({
  heading: HeadingLevel.HEADING_1,
  children: [
    new TextRun({
      text: "Title",
      bold: true,
      color: "FF0000",
    }),
  ],
});

html-docx-js 依赖 HTML/CSS 映射。

• 样式由输入的 HTML 决定，Word 负责解释。
• 复杂 CSS 可能在 Word 中渲染不一致。

// html-docx-js: 样式依赖 HTML
const html = `
  <h1 style="color: red; font-weight: bold;">Title</h1>
  <p>Content</p>
`;
// 样式保留程度取决于 Word 的 HTML 解析器
const blob = htmlDocx.asBlob(html);

mammoth 忽略大部分样式。

• 它关注内容结构（标题、段落），而非视觉样式。
• 输出干净的 HTML，适合 Web 展示。

// mammoth: 样式映射配置
const result = await mammoth.convertToHtml({ arrayBuffer: buffer }, {
  styleMap: [
    "p[style-name='Heading 1'] => h1:fresh"
  ]
});
// 可自定义样式映射，但默认忽略复杂格式

🖼️ 图片处理机制

docx 需要手动管理图片媒体。

• 图片必须作为媒体对象添加到文档实例中。
• 支持调整大小和环绕方式。

// docx: 插入图片
import { ImageRun } from "docx";
import cat from "./cat.png";

const paragraph = new Paragraph({
  children: [
    new ImageRun({
      data: cat,
      transformation: { width: 100, height: 100 },
    }),
  ],
});

html-docx-js 支持 Data URI 图片。

• 图片直接嵌入在 HTML 字符串中。
• 方便但可能增加文件体积。

// html-docx-js: 图片嵌入 HTML
const html = `
  <img src="data:image/png;base64,iVBORw0KGgo..." />
`;
const blob = htmlDocx.asBlob(html);

mammoth 提取图片为 Base64。

• 读取时可将图片提取为 HTML img 标签。
• 适合在网页上还原文档中的图片。

// mammoth: 提取图片
const result = await mammoth.convertToHtml({ arrayBuffer: buffer }, {
  convertImage: mammoth.images.imgElement(function(image) {
    return image.read("base64").then(function(base64) {
      return { src: "data:" + image.contentType + ";base64," + base64 };
    });
  })
});

🌐 运行环境支持

docx 通吃 Node.js 和浏览器。

• 在浏览器中生成 Blob 供下载。
• 在 Node 中写入文件系统。

// docx: 浏览器端保存
import { saveAs } from "file-saver";
const blob = await Packer.toBlob(doc);
saveAs(blob, "example.docx");

html-docx-js 主要在浏览器端使用。

• 设计初衷是为了前端导出。
• Node 端支持较弱。

// html-docx-js: 浏览器端保存
const blob = htmlDocx.asBlob(html);
// 通常配合 file-saver 使用

mammoth 通吃 Node.js 和浏览器。

• 在浏览器中读取 File 对象。
• 在 Node 中读取 fs 文件。

// mammoth: 浏览器读取文件
const fileInput = document.querySelector("input[type=file]");
const arrayBuffer = await fileInput.files[0].arrayBuffer();
const result = await mammoth.convertToHtml({ arrayBuffer });

📊 核心差异总结

💡 架构建议

docx 是企业级文档生成的首选 🏢。如果你的应用需要生成法律合同、正式报告或任何需要精确打印布局的文件，不要犹豫，选择 docx。虽然代码量较多，但它能避免格式错乱带来的后期维护成本。

html-docx-js 是快速原型的利器 🚀。如果你正在做一个博客系统或笔记应用，用户只想把当前页面存为 Word 备份，它的集成成本最低。但要做好心理准备，用户在 Word 中打开时可能会遇到细微的格式偏差。

mammoth 是内容摄入的网关 🚪。当用户上传图片到云端时，用它来提取文本进行搜索索引，或者在网页上预览文档内容。它生成的 HTML 干净且语义化，非常适合 Web 展示。

最终建议：在一个完整的文档管理系统中，你很可能同时需要 docx（用于导出报告）和 mammoth（用于导入预览）。不要试图用一个库解决所有问题，因为它们的设计初衷本身就是互补的。