Odoo11报表自定义页眉不显示问题求助（wkhtmltopdf 0.12.4）

我在帮朋友排查Odoo报表页眉问题时，遇到过和你完全一样的场景——页脚正常显示，页眉死活不出来，结合你的代码和环境，给你几个实用的排查和解决方向：

1. 先检查Odoo报表的PDF参数配置 #

wkhtmltopdf对页眉的加载逻辑和页脚不同，不能只靠模板里的<div class="header">来渲染，必须在报表的ir.actions.report.xml配置中明确指定页眉HTML文件路径。

比如你的报表配置应该类似这样：

<record id="report_your_custom" model="ir.actions.report">
    <field name="name">自定义报表</field>
    <field name="model">your.target.model</field>
    <field name="report_type">qweb-pdf</field>
    <field name="report_name">your_module.report_template</field>
    <!-- 关键：指定页眉页脚的独立HTML文件路径 -->
    <field name="pdf_options">{'header-html': '/your_module/static/src/html/report_header.html', 'footer-html': '/your_module/static/src/html/report_footer.html'}</field>
</record>

注意：把页眉和页脚分别做成独立的HTML文件，不要直接嵌入主报表模板中，wkhtmltopdf会单独加载这两个文件来生成页眉页脚。

2. 补全页眉HTML的图片路径与基础样式 #

你的当前代码里图片路径不完整，而且缺少必要的页面样式，容易导致加载失败或被遮挡：

正确的页眉HTML示例（report_header.html）： #

<!DOCTYPE html>
<html>
<head>
    <style>
        body { margin: 0; padding: 0; width: 100%; }
        .header { text-align: center; width: 100%; }
    </style>
</head>
<body>
    <div class="header">
        <!-- 补全图片完整文件名 -->
        <img height="160" src="/your_module/static/src/img/header_logo.png"/>
    </div>
</body>
</html>

确保图片文件确实存在于your_module/static/src/img/目录下，且Odoo进程有读取权限。

3. 调整主报表模板的页面边距 #

如果页眉图片高度是160px，主报表模板里必须留出足够的上边距，否则页眉会被主内容覆盖，看起来像是没显示：

在主报表模板的<style>中添加：

@page {
    margin-top: 5cm; /* 留出比160px更大的空间，避免遮挡 */
    margin-bottom: 5cm;
}

4. 用wkhtmltopdf命令行直接测试，排除Odoo干扰 #

在服务器上执行以下命令，直接用wkhtmltopdf渲染测试，确认是Odoo配置问题还是wkhtmltopdf本身的问题：

wkhtmltopdf --header-html /path/to/your/report_header.html --footer-html /path/to/your/report_footer.html https://your-odoo-url/test-page test_output.pdf

• 如果命令行生成的PDF能显示页眉，说明问题出在Odoo的报表配置上；
• 如果还是不显示，检查图片路径是否正确、页眉HTML是否有语法错误，或者wkhtmltopdf的权限是否能读取静态文件。

5. 注意wkhtmltopdf 0.12.4的特性 #

这个版本有个小坑：页眉里的图片必须用绝对路径（要么是服务器本地的绝对路径，要么是完整的HTTP URL），相对路径大概率加载失败。如果用Odoo的静态文件路径，确保开头是/module_name/...这种根相对路径。

内容的提问来源于stack exchange，提问作者Sibi S