pandoc 是目前 html 转 docx 唯一靠谱的选择，需配合 utf-8 编码、自定义 reference.docx 保留样式，并预处理远程图片；python-docx 不解析 html，bs4+python-docx 需手动映射语义，截图类方案不可编辑且质量差。
用 python-docx 直接写入 HTML 内容行不通
python-docx 本身不解析 HTML，add_paragraph() 或 add_run() 只接受纯文本或基础格式字符串，传入 "<p>hello</p>" 这类 HTML 片段会原样显示，不会渲染成段落。
常见错误现象：生成的 .docx 里一堆 <div>、<code><strong></strong> 标签字符，而不是加粗/换行效果。
- 别试图用
python-docx+ 正则替换 HTML 标签——语义丢失严重（比如嵌套<em><strong>test</strong></em>无法可靠还原） - 真正能保结构的路径只有：先解析 HTML → 提取语义（标题/列表/链接/图片等）→ 映射为 docx 元素
- 推荐用
bs4解析 +python-docx构建，但需自己处理样式映射（如<h2></h2>→style='Heading 2'）
用 pandoc 命令行最稳，但要注意编码和样式链
pandoc 是目前对 HTML → DOCX 转换兼容性最好、开箱即用程度最高的工具，它背后调用的是 Word 的 OpenXML 规范，不是模拟渲染。
典型命令：pandoc input.html -o output.docx
立即学习“前端免费学习笔记（深入）”；
- 中文乱码？加
--from=html --to=docx --charset=utf-8，确保输入 HTML 文件本身是 UTF-8 编码（BOM 会导致pandoc解析失败） - 样式丢失？默认用内置模板；想保留 CSS 中的字体/颜色，得用自定义 reference.docx：
pandoc input.html --reference-doc=my-style.docx -o output.docx - 图片路径失效？
pandoc默认只处理相对路径中的本地文件；远程图片（src="https://..."）会被忽略，需提前下载并改写src属性
浏览器打印为 PDF 再转 DOCX 是备选，但质量不可控
有人用 Chrome 的「另存为 PDF」+ 第三方 PDF→DOCX 工具（如 pdf2docx 库），这条路看似简单，实际问题集中：
- PDF 是图形流，文字可能被转为图片或路径，
pdf2docxOCR 准确率依赖内容清晰度，表格/公式极易错位 - 超链接、目录、页眉页脚在 PDF 阶段已固化，转回 DOCX 后基本不可编辑
- 如果原始 HTML 用了 flex/grid 布局，Chrome 渲染的 PDF 排版和 Word 原生排版逻辑冲突，转出 DOCX 后段落间距、缩进常异常
node-html-to-docx 不适合生产环境
这个 npm 包名字直白，但底层依赖 PhantomJS（已停止维护）或 Puppeteer 截图，本质是“把网页截图后塞进 DOCX”，不是结构化转换。
运行时会报错：Error: Failed to launch chrome 或 Cannot find module 'phantom'，尤其在无图形界面服务器上几乎必挂。
- 生成的 DOCX 实际是单张大图 + 少量文本层，复制粘贴文字困难，搜索不可用
- 字号、行高、分页完全不可控，A4 页面内多列布局会直接压扁
- 仅适合导出「展示快照」，比如周报截图归档；不能用于需后续编辑、审阅或插入修订痕迹的场景
真正要让 HTML 结构、语义、链接、列表都可编辑地进 DOCX，pandoc 是目前唯一靠谱的选择。但别忘了检查 reference.docx 里是否定义了对应 HTML 标签名的样式——比如没定义 code 样式，所有 <code>xxx 就会变成普通正文，连等宽字体都没有。
