React中使用html-to-docx导出HTML为docx异常如何解决

核心问题成因 #

• 本地导出文档显示方框：一是未配置对应字体（尤其是中文字体），Word无匹配字体时会渲染为方框；二是未将库返回的ArrayBuffer转为符合格式要求的Blob对象，文件结构本身存在异常。
• Linux服务器部署后功能失效：除上述Blob类型错误外，大概率是构建配置错误将html-to-docx识别为Node端依赖排除，导致线上环境调用时方法不存在；若使用SSR框架，也可能是将导出逻辑放在了服务端执行，浏览器环境下无对应DOM API导致报错。

修复实现 #

1. 修正核心导出逻辑 #

原有代码直接将Buffer传入createObjectURL的写法存在错误，必须先转为指定MIME类型的Blob，同时补充内存回收逻辑。
注意：传入HTMLtoDOCX的第一个参数必须是HTML字符串类型，不能直接传入DOM节点对象，需要通过dom.outerHTML或dom.innerHTML获取对应字符串后传入

exportToWord = async (e) => {
  const fileBuffer = await HTMLtoDOCX(myHTML, null, {
    table: { row: { cantSplit: true } },
    footer: true,
    pageNumber: true,
    // 新增字体配置，根据实际页面使用的字体调整
    fonts: [
      {
        name: "Microsoft YaHei",
        family: "Microsoft YaHei",
        weight: 400,
        style: "normal"
      },
      {
        name: "Arial",
        family: "Arial",
        weight: 400,
        style: "normal"
      }
    ],
    // 全局默认字体设置为已配置的字体
    defaultFont: {
      name: "Microsoft YaHei",
      size: 24 // 单位为半磅，24对应常用的12号字
    }
  });

  // 正确生成Blob，指定docx对应的标准MIME类型
  const blob = new Blob([fileBuffer], {
    type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  });

  const link = document.createElement("a");
  link.href = window.URL.createObjectURL(blob);
  link.download = "SampleReport.docx";
  document.body.appendChild(link);
  link.click();
  // 移除临时节点、释放内存
  document.body.removeChild(link);
  window.URL.revokeObjectURL(link.href);
}

2. 部署环境校验 #

• 若使用Vite/Webpack构建，检查配置中是否将html-to-docx加入了external依赖排除列表，若有需移除，保证库代码被正确打包到前端静态资源中。
• 若使用Next.js/Remix等SSR框架，需将导出逻辑所在组件标记为客户端组件（Next.js在文件顶部添加'use client'标记），禁止在服务端执行该导出方法。

额外注意事项 #

• 如果HTML中包含外部图片，需先将图片转为base64格式内嵌到HTML中，否则导出的docx内图片无法正常显示。
• 复杂CSS样式（如flex、grid、部分伪类选择器）html-to-docx支持度有限，导出前尽量将复杂布局转为表格结构，避免样式错乱。
• 如果需要实现跨设备无缺字显示，可以将字体文件转为base64嵌入到字体配置中。

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