Next.js+TypeScript项目导出兼容Mac Pages的DOCX文件问题

核心思路 #

避开依赖微软专属命名空间的HTML转DOCX方式，改用遵循Open XML标准的工具，同时确保工具具备可靠的TypeScript类型支持。

可行方案 #

1. 使用mammoth（推荐，维护活跃+原生TS支持） #

mammoth是专注于Open XML文档处理的成熟库，自带TypeScript类型声明，能生成符合标准的DOCX文件，天然兼容Pages、Word等主流办公软件：

• 安装依赖：

  npm install mammoth @types/mammoth
  

• 核心代码示例（可用于Next.js客户端组件或API路由）：

  import mammoth from 'mammoth';
  import { saveAs } from 'file-saver';
  
  // 传入页面要转换的HTML内容
  const htmlToConvert = `<div><h1>页面标题</h1><p>正文段落内容</p></div>`;
  
  const exportToDocx = async () => {
    // 转换为符合标准的DOCX缓冲区
    const docxBuffer = await mammoth.convertToDocx({ rawHtml: htmlToConvert });
    // 生成Blob并触发下载
    const blob = new Blob([docxBuffer], { 
      type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' 
    });
    saveAs(blob, 'exported-document.docx');
  };
  

2. 使用docx库（适合精细化文档控制） #

docx是专门用于构建DOCX文档的TS友好库，支持自定义文档结构、样式，维护状态良好：

• 安装依赖：

  npm install docx @types/docx
  

• 核心代码示例：

  import { Document, Packer, Paragraph, TextRun } from 'docx';
  import { saveAs } from 'file-saver';
  
  const generateStandardDocx = async () => {
    // 构建DOCX文档对象模型
    const doc = new Document({
      sections: [
        {
          children: [
            new Paragraph({
              children: [new TextRun('页面标题')],
              heading: 'Heading1',
            }),
            new Paragraph('正文段落内容'),
            // 可根据页面内容扩展更多元素
          ],
        },
      ],
    });
  
    // 转换为缓冲区并下载
    const buffer = await Packer.toBuffer(doc);
    const blob = new Blob([buffer], { 
      type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' 
    });
    saveAs(blob, 'custom-document.docx');
  };
  

  注：此方案需要将页面HTML内容映射为DOCX的文档对象，适合需要精细控制样式、布局的场景。

3. 手动构建标准Open XML结构（高度定制化场景） #

DOCX本质是包含特定XML文件的ZIP包，若需要完全自定义文档内容，可借助zip.js（带TS声明）打包符合ISO/IEC 29500标准的XML文件：

• 安装依赖：

  npm install zip.js @types/zip.js
  

• 核心逻辑：生成document.xml、content_types.xml等必需的标准XML文件，通过zip.js打包为ZIP并命名为.docx后缀，这种方式生成的文件完全兼容所有支持Open XML的软件。

避坑提示 #

• 彻底弃用带有微软专属命名空间（如xmlns:o='urn:schemas-microsoft-com:office:office'）的HTML模板，这类非标准内容会被Pages判定为无效格式。
• 测试阶段优先用Mac Pages打开验证，确保生成的文件严格遵循Open XML标准。

内容的提问来源于stack exchange，提问作者Pinkney