报告生成:PDF里的那些坑
上篇和大家分享了数据库设计的底层逻辑，这篇咱们聚焦最折腾我的环节——试验报告生成。
做这套试验数据管理系统报告生成，踩了一个又一个坑。一份正式的试验报告，从封面、页眉、页码，到签名位置、表格对齐、图片排版，每个都要慢慢的调。
我前后试了Word和HTML两种方案，折腾了很久，才最终用ReportLab跑通所有流程。这篇就把所有踩过的坑、最终的解决方案。
第一版：Python生成Word（docx）
一开始觉得很完美，用python-docx库生成Word模板，填充数据就能出报告。但实际使用后功能有限：复杂格式（如精确控制单元格位置、插入带签名的图片）根本实现不了，python-docx库的适配性远远不够。
第二版：直接用HTML展示
网页格式的优势是跨设备兼容，谁打开都一样，但用于正式报告，打印混乱：网页打印时经常缺页眉、丢页码，打印效果依赖每个人的浏览器设置，无法统一，公司上传格式不符。
最终选择：直接用ReportLab生成PDF
虽然用ReportLab写代码麻烦一点，但胜在精准可控——代码里能控制每一个元素的位置、大小、格式，生成的PDF文件，无论在谁的电脑上打开、打印，效果都完全一致，完美符合试验报告的归档要求。
结论：正式场合使用的报告，别折腾其他格式，直接用PDF，一步到位。
二、中文字体：最基础也最折腾，整整卡了两天
ReportLab的一个致命问题：默认不支持中文。第一次生成PDF，打开后所有中文全是方框，瞬间心态崩了。
我翻了无数教程，试了SimHei.ttf、微软雅黑等多种字体，注册后依旧无效，折腾一上午，方框还是方框。后来才明白：ReportLab需要正确注册TrueType字体，选对字体是关键。
最终解决方案：文泉驿微米黑（开源免费，跨平台适配）
开源免费：采用Apache 2.0和GPL v3双授权，个人、商业使用均免费（需保留版权声明）；
字符齐全：包含20932个汉字，完整覆盖GB2312/Big5以及GBK标准字符集，满足试验报告所有中文需求；
字体下载链接http://wenq.org/wqy2/index.cgi?action=browse&id=MicroHei&revision=3.0
三、页码：看似简单，实则藏着大问题
试验报告对页码有明确要求：封面不显示页码，从正文开始标注“第X页 共Y页”。ReportLab默认的页码机制不支持这种样式，又折腾了好一阵。
一开始尝试在每页画布上手动计算页码，但ReportLab的渲染顺序是“先画内容，后画页码”，绘制页码时，根本不知道总共有多少页，无法实现“共Y页”的效果。
最终解法：自定义NumberedCanvas，统一渲染页码
核心思路：先把所有页面的状态保存下来，等所有页面都渲染完成、知道总页数后，再重新遍历页面，统一绘制页码。
四、表格跨页：表头消失，读者看懵了
试验数据表包含500+项目，内容很长，一页根本放不下。ReportLab会自动实现表格跨页，但跨页后，下一页的表格没有表头
解决方案：添加repeatRows=1参数
创建表格时，添加一个简单的参数，就能让表头在每一页都重复显示，完美解决跨页表头消失的问题：
Table(table_data, repeatRows=1)
额外坑：表格宽度超出页面，被截断
解决了表头问题，又遇到新坑：表格太宽，超出A4纸范围，ReportLab不会自动缩窄，而是直接截断。
经过多次调试，我确定了最优列宽（适配A4纸，左右边距各2cm），大家可直接复用：
|
列名
|
宽度
|
|
序号
|
1.0 cm
|
|
二级项目
|
3.5 cm
|
|
测试项目
|
7.5 cm
|
|
单位
|
2.0 cm
|
|
数据
|
2.0 cm
|
总宽度16cm，A4纸内容区域剩余17cm，留1cm缝隙，完美适配，不会被截断。
五、图片排版：不能乱跑，还要整齐统一
原尺寸插入：图片大小不一，有的太大撑爆页面，有的太小缩在角落，排版混乱不堪；
固定宽度缩放：竖屏照片被缩得很窄，横屏照片正常，整体排版不整齐，视觉效果差。
最终方案：固定高度，宽高比自适应
核心逻辑：固定图片高度为5cm，宽度按原宽高比自动计算；若宽高比超过1.6（过于宽大的照片），则按1.6计算，避免图片被过度压扁，保证排版整齐。
排版技巧：用Table把图片和图片标题包裹在一起，每行放两个Table，实现一页两张图片的规范排版，整齐又美观。
六、给想动手的人：AI帮你写代码，少踩80%的坑
PDF生成这块，坑多且琐碎，从零敲代码很费时间。我的经验是：别零敲碎打，一次性把所有需求说清楚，让AI帮你生成完整框架代码，你再根据实际情况微调，效率能提升一倍。
下面是我整理的AI提示词模板，你可以直接复制使用（ChatGPT、Claude、DeepSeek等AI都适用），能生成完整的ReportLab脚本框架，关键位置用占位符标注，填数据就能用。
请帮我用Python的ReportLab库生成一份试验报告PDF。要求如下：
– 需要自定义Canvas，实现封面不显示页码、正文显示”第X页 共Y页”的功能
– 每页都要有页眉：中文一行”XXXXXX”，英文一行”XXXXXX”，下面一条横线（封面不显示页眉）
– 使用文泉驿微米黑字体（wqy-microhei.ttc）
– 注册字体名称：ChineseFont（常规）、ChineseFont-Bold（粗体）
– 顶部：左边”核心商密XXXXXX”，右边”编号：{编号}”
– 公司名称：”XXXX” + “XXXX”（居中，大号字）
– 下方显示：”名称：{报告名称}”、”编制单位：XXXXX”
– 签名区域（用表格布局，三列：签名类型、签名图片、日期），四个签名：编制、校对、审核、批准
– 图片要求：高度固定5cm，宽高比自适应，超过1.6的按1.6算，每行放两张
请生成完整的Python脚本框架，关键位置用{占位符}表示待填充的数据。
AI生成脚本后，你只需替换占位符（如报告编号、报告名称、签名图片路径等），再微调一下尺寸、位置，就能快速跑通PDF生成功能，少踩很多坑。
九、生成一份报告，从1小时到30秒
以前手动生成一份试验报告，流程繁琐到崩溃：找数据、填表格、插图片、调格式、核对页眉页码、打印归档，至少耗时1小时，还容易出错。
现在用系统生成报告，只需点一下按钮，30秒就能完成：500+测试项目、15个大类、所有试验图片，全部自动排版、自动分页、自动添加页眉页码、自动对齐签名和日期。
生成的PDF文件，直接可以打印、归档、发给领导，再也不用为格式问题反复调整，彻底解放双手。
下篇预告
三篇推文下来，从项目启动（摆脱Excel内耗），到数据库设计（数据有序管理），再到报告生成（高效出合规报告），系统核心功能已经全部讲完。
下篇我换个角度，和大家聊聊最基础也最容易卡住的环节——整个系统环境是怎么搭起来的，全是实操配置技巧：
Python怎么装？Anaconda和直接安装，选哪个更省心？
MySQL怎么配置？用户名、密码、编码、连接池，一步到位；
PyCharm怎么设置？解释器、虚拟环境、代码格式化，提高开发效率；
部署到服务器的坑？端口、防火墙、开机自启，怎么解决？
这些配置看似琐碎，但真动手时，每一步都可能卡住。下篇把实际配置方法过一遍，给真想动手搭建系统的同行，指一条少走弯路的路。
互动话题：你装Python环境时遇到过什么坑？比如虚拟环境配置、库安装失败等，评论区聊聊你的踩坑经历和解决方案～
夜雨聆风
