先说结论
在 Odoo 里，用户点“打印”并不是模板文件直接变成 PDF。
中间通常至少有这几层：
- report action
- 报表模型/数据准备
- QWeb 模板渲染成 HTML
- 再由 PDF 引擎输出成最终文件
所以报表问题很多时候不是“模板坏了”这么简单，而是整条输出链里某一层出了偏差。
为什么很多人只盯模板会排错很慢
因为用户最直观看到的是：
- 打印页面长什么样
- 某字段有没有显示
- 排版对不对
所以第一反应常常是只改 QWeb 模板。
但实际上，报表结果还强烈依赖：
- action 调的是哪份报表
- 传入了哪些记录
- 渲染上下文里准备了什么数据
- 最后 PDF 引擎如何解释 HTML/CSS
也就是说：
报表模板只是输出链的一层，不是全部。
report action 真正负责什么
它更像是在声明：
用户这次打印请求，应该走哪一套报表输出入口。
它通常会决定：
- 绑定哪个模型
- 用哪份 QWeb 模板
- 输出成什么类型
- 打印动作如何暴露在界面上
所以 action 更像“报表入口定义”，而不是排版本体。
QWeb 模板真正负责什么
QWeb 模板最核心负责的是：
- 如何组织页面结构
- 哪些字段显示
- 循环和条件怎么展开
- 页面长什么样
也就是说，它主要负责：
把准备好的业务数据组织成可渲染页面。
如果上游数据没准备好，模板本身写得再漂亮也没用。
为什么 HTML 正常不等于 PDF 正常
这是报表里很经典的坑。
因为 QWeb 通常先渲染出 HTML，再交给 PDF 引擎处理。
这意味着：
- 浏览器里看着还行
- 到 PDF 里却可能换页怪异、宽度错位、样式丢失
原因不是业务数据变了，而是 PDF 引擎对 HTML/CSS 的支持和浏览器不是一回事。
所以报表开发里一定要记住：
HTML 预览通过，不等于 PDF 成品就一定通过。
为什么报表问题常常要分层排查
一个很稳的排查思路通常是：
1. action 对不对
先确认是不是走到了正确报表入口。
2. 传入记录对不对
别一开始就怪模板。
3. 数据上下文是否完整
有些字段不显示，根因是上游没准备。
4. QWeb 结构是否合理
再看模板循环、条件和布局。
5. PDF 引擎渲染是否带来版式偏差
最后再看输出差异。
这样排查比一上来就狂改模板快得多。
实战里最容易踩的 5 个坑
1. 只会改模板，不看 action 和数据准备
定位会很慢。
2. HTML 看起来对，就以为 PDF 一定对
这在报表里非常危险。
3. 报表里塞太多复杂业务计算
模板会越来越难维护。
4. 把版式问题和数据问题混着查
很容易越查越乱。
5. 认为打印只是 UI 末端
实际上它是完整输出链的一部分。
一句话记忆法
把这条链记成一句话：
report action 决定走哪条报表入口，QWeb 负责把业务数据组织成页面，PDF 引擎再把页面变成最终文件。
理解这一句，Odoo 报表链路就没那么神秘了。
DISCUSSION
评论区