python-docx不解析HTML，需先用BeautifulSoup解析再映射为add_heading()等操作；html-to-docx默认配置易出错；生产推荐无头浏览器+pdf2docx；LibreOffice适合静态HTML批量转换。
直接用 python-docx 写入 HTML 字符串会失败——Word 里真出现 <p>Hello</p>，不是段落，是纯文本。
为什么 document.add_paragraph('标题
') 不行
python-docx 不解析 HTML，它只操作 .docx 的底层 XML 结构。传进去什么字符串，就原样写进文档；<h2> 标签不会被识别为标题样式，也不会触发自动编号或大纲层级。
- 常见错误现象：
document.add_paragraph('<h2>标题</h2>')→ Word 中显示“<h2>标题</h2>”字面量 - 根本原因：HTML 是标记语言，
python-docx是对象模型驱动，二者语义不互通 - 必须先做 HTML → DOM 节点解析（如用
BeautifulSoup），再按标签名映射到Document方法（add_heading()、add_paragraph()、add_table()）
html-to-docx 默认配置几乎必翻车
这个 npm 包看似开箱即用，但默认关闭关键特性，表格错位、样式丢失、图片空白是常态。
- 内联样式全失效？因为
parseHtmlStyles: false是默认值，必须显式设为true - 表格变成一列堆叠？没开
table.styleMappings: true，rowspan/colspan和<th>语义全丢 - 网络图片 404？
html-to-docx不走浏览器上下文，不支持src="https://..."，只认data:image/...或本地可读路径 - 嵌套
<table>直接消失？该库对深度嵌套无处理逻辑，需前端预扁平化
最稳的生产级路径：无头浏览器 + pdf2docx
用 Chrome/Edge 渲染 HTML → PDF → 转 DOCX，保真度远高于纯 Python 解析，尤其对 CSS 布局、字体、边框、分页有效。
立即学习“前端免费学习笔记（深入）”；
- 推荐工具链：
playwright（Python/JS）启动无头浏览器，调用page.pdf()；再用pdf2docx转换 - 别用
selenium + chromedriver：PDF 生成接口不稳定，常卡在 JS 加载完成判断上 -
pdf2docx加multi_processing=True可提速，但若 HTML 含float: left，需提前加@media print { float: none }重置布局 - 注意：转换后表格可能微偏移、页眉页脚丢失——这是 PDF → DOCX 的固有损耗，无法完全避免
简单场景别绕弯：LibreOffice 命令行
适合批量、格式较标准（语义化标签多、CSS 少）、无需动态渲染的 HTML，CI/定时任务首选。
- 命令示例：
libreoffice --headless --convert-to docx --outdir ./output ./input.html - 必须装完整 LibreOffice（≥ 7.0），仅 runtime 不行；旧版对 UTF-8 和内联样式支持差
- 图片路径会失效：相对路径
images/a.png被当成本地文件系统路径，需提前复制资源目录，或改用绝对路径 / base64 - 不执行 JavaScript：动态插入的 DOM（如
document.createElement）不会出现在结果中
真正麻烦的从来不是“能不能转”，而是“哪些结构会塌陷、哪些样式会蒸发、哪些图片会消失”。每种方案都有明确的失效边界，选之前先拿你的实际 HTML 样本跑一遍，比读十篇教程都管用。
