weasyprint安装失败或中文乱码的主因是系统级依赖缺失与字体未显式注册；需先用homebrew（macos）、apt（linux）或预编译包（windows）安装cairo等底层库，再通过fontconfiguration.add_font()注册中文字体文件，并在css中配合@font-face或代码中指定font_config。
weasyprint 无法安装或报错 cairocffi 缺失
WeasyPrint 依赖底层绘图库 Cairo，而 cairocffi 是其 Python 绑定。在 macOS 或 Windows 上直接 pip install weasyprint 常因缺少系统级 Cairo 库失败。
- macOS：先用 Homebrew 安装
cairo、glib、pango：brew install cairo pango gdk-pixbuf libffi - Windows：推荐使用预编译的二进制包，运行
pip install weasyprint --only-binary=weasyprint - Linux（如 Ubuntu）：运行
sudo apt-get install libpango-1.0-0 libcairo2 libglib2.0-0后再 pip 安装 - 若仍报
ImportError: cannot import name 'ffi' from 'cffi'，尝试升级cffi：pip install --upgrade cffi
中文乱码或字体不显示
WeasyPrint 默认不加载系统中文字体，HTML 里用了 font-family: "Microsoft YaHei", sans-serif 也照样空白或方块。
html-to-pptx-converter
下载
使用 PptxGenJS 和 Python 解析，将结构化的 HTML/CSS 幻灯片内容转换为原生、可编辑的 PowerPoint（.pptx）演示文稿。
- 必须显式指定中文字体路径，例如：
@font-face { font-family: "SimSun"; src: url("/path/to/simsun.ttc"); } - 更稳妥的做法是用
weasyprint.HTML(...).write_pdf(..., font_config=font_config)配合FontConfiguration()，并提前调用font_config.add_font(...)注册 ttf/ttc 文件 - 注意：ttf 文件需有完整字体名称（可用
fc-list : family查 Linux，或 Font Book 查 macOS），且 WeasyPrint 不支持 woff/woff2 - 常见坑：CSS 中
font-weight: bold若对应字体文件不含粗体字形，会静默回退为常规体，而非报错
页面尺寸、页边距与分页控制失效
CSS 的 @page 规则对 WeasyPrint 生效，但部分属性被忽略或行为不同——比如 break-inside: avoid 在表格行上常无效。
- 设置纸张大小必须写全：
@page { size: A4; margin: 2cm; }，仅写size: a4（小写）可能被忽略 - 避免在容器上用
height: 100vh，WeasyPrint 不支持视口单位，会导致内容截断 - 强制分页用
page-break-before: always或break-before: page（后者是新标准，WeasyPrint ≥53 支持） - 表格跨页时，
thead不会自动重复，需手动添加thead { display: table-header-group; }并确保其在每页顶部渲染
动态 HTML（含 JS 渲染内容）转 PDF 为空白
WeasyPrint 是纯 CSS 渲染引擎，不执行 JavaScript。如果你传入的是一个含 document.write 或 Vue/React 初始化后才生成 DOM 的 HTML 字符串，PDF 里只会看到初始空壳。
- 务必确保传给
weasyprint.HTML(string=...)或weasyprint.HTML(filename=...)的 HTML 已完成所有 JS 渲染 - 典型做法：用 Playwright 或 Selenium 先访问页面、等待 JS 执行完毕、再
page.content()获取最终 HTML，再交给 WeasyPrint - 若只是简单数据填充，建议用 Jinja2 模板直接生成静态 HTML，而非依赖前端 JS
- 注意：WeasyPrint 不支持
canvas、svg filter、CSS 变量（--var）等较新特性，渲染前应做降级处理
@page 写法，稍有偏差就静默失败，看不出错在哪。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
