用 python-docx 生成中文 Word 简历模板时…

python-docx 生成中文 Word 表格模板的三个高频坑与解法，全部靠「渲染→目视」闭环才能发现（语法/结构校验查不出来）： 坑1：用 1×1 表格当整页外框 → 嵌套表格装全部内容会跨页断裂，把后续模块整块推到第 2 页。解法：改用 Word 原生页面边框 w:pgBorders（挂在 sectPr 上，offsetFrom=text），不参与分页、绝不挤内容。 坑2：对合并单元格的同一个 tc 反复调用 set_borders/set_shading → 每次 append 累积多个 w:tcBorders/w:shd，Word 只取第一个，导致后设的边框丢失（照片格无边）。解

适用场景

解决思路

1. python-docx 生成中文 Word 表格模板的三个高频坑与解法，全部靠「渲染→目视」闭环才能发现（语法/结构校验查不出来）：
2. 坑1：用 1×1 表格当整页外框 → 嵌套表格装全部内容会跨页断裂，把后续模块整块推到第 2 页。解法：改用 Word 原生页面边框 w:pgBorders（挂在 sectPr 上，offsetFrom=text），不参与分页、绝不挤内容。
3. 坑2：对合并单元格的同一个 tc 反复调用 set_borders/set_shading → 每次 append 累积多个 w:tcBorders/w:shd，Word 只取第一个，导致后设的边框丢失（照片格无边）。解法：append 前先遍历删掉同名子元素（for el in tcPr.findall(qn(tag)): tcPr.remove(el)）。
4. 坑3：只设 cell.width 列宽不生效 → fixed layout 下必须同时重写 w:tblGrid 的 gridCol 宽度 + tblLayout=fixed + tblW，否则窄列文字（电话号/邮箱）被断成两行。
5. 闭环命令：python3 gen.py && soffice --headless --convert-to pdf x.docx --outdir /tmp/w && pdfinfo x.pdf | grep Pages && pdftoppm -r 110 -png x.pdf w && 用 vision 逐个核对：外框四边完整/竖排标题真竖排/长串不换行/无空色块/单页。竖排用 w:text
6. 注意：rm -rf 临时目录在 macOS 上会触发审批通道（已知 bug），改用 mkdir -p 新目录，不删旧目录。