WeasyPrint 渲染失败主因是 CSS 支持有限（不支持 Flexbox/Grid）、外部资源默认不加载、字体需 @font-face 显式声明并 font_config 注册、图片须用 file:/// 绝对路径、避免 position: fixed 而改用 @page + running()、中文需 UTF-8 编码且禁用 Latin-1、HTML 必须为 str 类型、分页依赖 Paged Media 规范、性能问题源于纯 Python 渲染，优化需禁用图片加载、避免 Base64、预编译 CSS。
WeasyPrint 渲染 HTML 模板失败：CSS 不生效或布局错乱
根本原因通常是 WeasyPrint 对 CSS 支持有限，不支持 Flexbox、Grid 或部分现代属性，且默认不加载外部网络资源（比如 CDN 字体、远程图片）。
- 本地字体必须用
@font-face显式声明，并通过font_config注册路径，不能只靠系统字体名 - 所有 CSS 最好内联（
<style>标签），避免@import或外部<link rel="stylesheet"> - 图片路径要用绝对文件路径（
file:///协议），相对路径在 WeasyPrint 中基本无效；Flask 的url_for()生成的 HTTP 地址会被直接忽略 - 避免使用
position: fixed做页眉页脚——它在分页时行为不可控，改用@page规则 +running()函数
Flask 中传入动态数据后 PDF 内容为空或报 UnicodeEncodeError
WeasyPrint 默认用 Latin-1 编码处理字符串，遇到中文或特殊符号会崩，且 Jinja2 渲染后的 HTML 若含未转义的 HTML 实体（如 ）也可能触发解析异常。
- 渲染模板前务必用
render_template_string()或render_template()生成完整 HTML 字符串，再传给HTML(string=...)，别传模板对象 - 确保 Flask 的
app.jinja_env.autoescape = True（默认开启），防止 XSS 同时也避免原始 HTML 被错误拼接 - HTML 字符串必须是
str类型，不能是bytes；如果从文件读取，用open(..., encoding='utf-8') - 若用
HTML(filename=...)，文件路径必须是绝对路径，且文件编码为 UTF-8 无 BOM
生成带分页/页眉页脚的 PDF 报告
WeasyPrint 的分页控制依赖 CSS Paged Media，不是靠 Python 逻辑切分内容。页眉页脚需用 @page 和 running() 配合 element() 提取内容，不能简单套用 div。
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
- 在 HTML 中定义一个带
id="page-header"的元素，然后在 CSS 里写：@page { @top-center { content: element(page-header); } } - 页码用
counter(page)，总页数用counter(pages)，但注意它们只在@page规则中有效 - 强制分页用
page-break-before: always或break-before: page（后者更推荐），别用<div style="page-break-after: always">—— 兼容性差 - 表格跨页断裂很常见，加
table { break-inside: avoid; }可缓解，但无法 100% 避免；复杂报表建议按逻辑段落拆成多个<section>并手动控制分页点
PDF 导出慢或内存暴涨
WeasyPrint 是纯 Python 渲染器，解析复杂 HTML+CSS 时 CPU 和内存开销明显，尤其在高并发或大报表场景下容易卡住或 OOM。
立即学习“Python免费学习笔记（深入）”；
- 禁用图片加载可大幅提速：
HTML(...).write_pdf(..., presentational_hints=True)，再配合url_fetcher返回空响应处理图片请求 - 避免在模板中嵌入 Base64 图片（
data:image/...），它们会显著拖慢解析；改用本地文件 +file://路径 - 不要在每次请求都重新编译 CSS；把常用样式预编译为字符串，复用
CSS(string=...)实例 - 生产环境别用
debug=True启动 Flask，WeasyPrint 在 debug 模式下会额外做 DOM 校验，性能下降 3–5 倍
