python-docx 不能直接解析 HTML，需用 pandoc 命令行工具转换，它兼容性最好、支持样式和图片，推荐预处理 HTML 清洗冗余代码后再调用。
用 python-docx 直接写 Word？不行，它不解析 HTML
想用 python-docx 把 HTML 字符串“塞进去”生成 .docx？会报错或只显示纯文本。python-docx 只能操作 Word 的底层 XML 结构，不带 HTML 解析器。真正能吃 HTML 的库是 docxtpl（需模板）或更轻量的 pydocx（已停更），但最稳的是 python-docx + beautifulsoup4 手动转换——不过代价是得自己处理标签映射。
-
python-docx本身没有add_html()方法，所有“HTML 转 Word”都绕不开解析和重建 - 简单段落、加粗、换行可用
bs4提取后逐段调用paragraph.add_run()+ 设置.bold/.italic - 表格、列表、嵌套 div 会立刻变复杂：Word 没有“div”，得转成
table或分节，python-docx不自动做语义降级
推荐方案：pandoc 命令行 + Python 调用
本地装好 pandoc 后，它是目前对 HTML 到 .docx 兼容性最好、开箱即用的工具。它把 HTML 当作中间源，按 Word 的样式规则渲染，支持内联样式、class、基础 CSS（如 font-weight）、表格、图片路径（相对/绝对）。
- 安装：
brew install pandoc（macOS）或去 pandoc.org/installing 下载对应版本 - 基础命令：
pandoc input.html -o output.docx，默认用内置模板，格式干净 - 想保留原始样式？加
--standalone和自定义 reference.docx：pandoc input.html -o output.docx --reference-doc=custom.docx - Python 中调用：
import subprocess; subprocess.run(["pandoc", "in.html", "-o", "out.docx"])，注意路径别含中文空格
用 weasyprint 先转 PDF 再转 DOCX？不推荐
有人试过 weasyprint 渲染 HTML 成 PDF，再用在线工具或 pdf2docx 转——这步极易崩。PDF 是固定布局，转 DOCX 时文字错位、表格分裂、图片丢失很常见，尤其含中文或 CSS Flex/Grid 时。
-
weasyprint输出的 PDF 本质是“打印快照”，不是可编辑文档结构 -
pdf2docx对扫描式 PDF 效果差，对 WeasyPrint 生成的矢量 PDF 也好不到哪去，convert_pdf_to_docx()经常返回空段落 - 多页 HTML → PDF → DOCX，链路长、失败点分散，调试成本远高于直接用
pandoc
HTML 文件里含本地图片怎么处理？
pandoc 默认只认绝对路径或 URL 图片；相对路径（比如 <img src="images/logo.png" alt="html文件怎么转换成word_html转word文档格式教程【攻略】" >）在执行时会报 Could not find image 错误，除非你指定工作目录或改写路径。
立即学习“前端免费学习笔记（深入）”；
- 最简方案：用
os.chdir()切到 HTML 所在目录再跑pandoc，确保所有src路径以当前目录为基准 - 更可靠：预处理 HTML，把相对路径转成绝对路径，用
pathlib.Path(html_path).parent / "images/logo.png"拼出真实路径再写回src - 避免 base64：虽然能把图片转成 data URI 嵌入 HTML，但
pandoc对超长 base64 支持不稳定，且生成的 .docx 体积暴增
真正卡住人的往往不是“怎么转”，而是 HTML 里混了前端框架残留的 data-v-xxx 属性、动态插入的 style 标签、或者用了 Tailwind 的 utility class——pandoc 不执行 JS，也不懂这些 class 含义，只会原样忽略。如果 HTML 是从网页上右键“查看页面源代码”拿的，大概率带一堆无用结构，先用 bs4 清洗再交给 pandoc 更省心。
