HTML如何转换成Word文档？

html-to-docx需显式启用parseHtmlStyles和table.styleMappings参数，并预处理HTML：内联化CSS、扁平化表格、转base64图片，否则易出现样式丢失、表格错位、图片空白等问题。

html-to-docx 是目前最可控、可集成的方案，但直接用它跑默认配置大概率会翻车——表格错位、图片消失、中文换行异常是高频问题。关键不在“能不能转”，而在“怎么配参数+怎么预处理HTML”。

为什么 HTMLtoDOCX() 默认不解析内联样式？

因为库默认关闭 parseHtmlStyles，所有 style="font-size:14px; color:#333" 这类内联样式会被忽略。你看到的 Word 文档字体统一、无颜色、无缩进，基本就是这个原因。

必须显式启用：

const docxBuffer = await HTMLtoDOCX(htmlContent, null, {  parseHtmlStyles: true});

注意：该参数只影响内联样式（style 属性），不处理 <style> 标签或外部 CSS。如果 HTML 里用了 class + 外部样式表，得先用工具内联化（比如 critters 或手动提取）。

table.styleMappings 不开，合并单元格就废了

HTML 中的 rowspan/colspan 在 Word 里不会自动还原，除非打开表格样式映射：

立即学习“前端免费学习笔记（深入）”；

{  table: {    styleMappings: true  }}

不开这个，表格会变成“每个单元格独立一行”，看起来像乱码。另外，<th> 标签默认不加粗、无背景色，也要靠 styleMappings 激活语义映射。

常见踩坑点：

• 只开了 parseHtmlStyles 但没开 table.styleMappings → 表格结构崩坏
• HTML 表格嵌套过深（比如 <td><table>...</table></td>）→ 转换后子表丢失或错位，建议扁平化处理
• 用 CSS 设置 border-collapse: collapse → Word 不识别，得用 border 内联属性替代

本地图片能显示，网络图片 404？不是跨域问题，是路径没转 base64

html-to-docx 不支持直接加载远程 URL 图片（如 <img src="https://example.com/logo.png">），也不走浏览器上下文，所以 CORS、缓存、鉴权全无效。它只认 data:image/xxx;base64,... 或相对路径（且文件得在 Node.js 进程可读范围内）。

解决方法只有两个：

• 提前把网络图片下载并转成 base64（用 axios + Buffer.from(...).toString('base64')）
• 或改用 html-docx-js 配合前端 fetch + FileReader 在浏览器里做转换（避开 Node.js 文件系统限制）

别信“设置 ignoreImageErrors: true 就能跳过”的说法——那只是让转换不报错，图片照样空白。

复制粘贴不是备选方案，而是快速验证基准线

在写任何代码前，先用浏览器打开 HTML → Ctrl+A → Ctrl+C → Word 里 Ctrl+V（选“保留源格式”）。这一步能立刻告诉你：原始 HTML 的语义结构是否合理（比如有没有用 <h1>~<h6>，列表是否用 <ul>/<ol>），以及哪些样式 Word 原生就吃不住（比如 Flex 布局、CSS Grid）。

如果粘贴后标题层级、段落间距、代码块背景都对，说明你的 HTML 已足够“Word 友好”，后续编码只需补足图片和表格细节；如果连基础结构都塌了，优先重构 HTML，而不是堆配置参数。