服务器生成不了PDF,先别急着重装系统,八成是字体缺失、依赖库版本不匹配或者临时目录权限出了问题。 下面按“看日志、查字体、对环境、调配置”的顺序,把常见坑挨个拆开讲清楚。
服务器生成pdf失败常见原因排查清单
文件大小为0或直接报错
先做三件事:看日志、看磁盘、看权限。
tail -n 50 /var/log/你的应用.log df -h ls -ld /tmp /你的输出目录
- 磁盘满了:
No space left on device会直接让生成进程中断。 - 临时目录没写权限:很多PDF库会往
/tmp写中间文件,运行用户必须是可写状态。 - 输出路径不存在:代码里
mkdir -p先建目录,再写文件。 - 内存不够:
Cannot allocate memory或进程被OOM Killer杀掉,用dmesg -T | grep -i oom确认。
| 报错关键词 | 优先排查方向 | 处理动作 |
|---|---|---|
| Permission denied | 目录权限、SELinux | 改属主、检查安全策略 |
| No space left | 磁盘、inode | df -h和df -i都看 |
| Cannot allocate memory | 内存、并发数 | 降并发、加swap或升配 |
| timeout | 网络资源、页面过大 | 本地化字体/CSS,调超时 |
中文变方块Linux服务器pdf生成乱码怎么解决?先查字体
服务器不像Windows自带微软雅黑,缺中文字体是最高频原因。
fc-list :lang=zh
如果输出为空,按发行版装字体:
- Ubuntu/Debian:
apt install fonts-wqy-zenhei fonts-wqy-microhei - CentOS/RHEL:
yum install wqy-zenhei-fonts wqy-microhei-fonts
装完刷新缓存:fc-cache -fv。
代码侧也要跟上:
- wkhtmltopdf:加
--encoding utf-8,确认CSS里font-family指向已安装字体。 - Puppeteer:页面渲染完等
await page.evaluateHandle('document.fonts.ready')再导出。 - Java iText:用
FontFactory.register("/usr/share/fonts/...ttf")注册具体字体文件,不要依赖系统默认。
行业共识认为,中文PDF乱码多数不是编码问题,而是服务器上根本没有对应字形文件,据开源社区公开文档,wkhtmltopdf在无中文字体的Linux环境会回退到默认字体,方块就这么来的。
本地和服务器生成pdf结果不一致对比:环境差异是根因
同一份代码,本地好好的,上服务器就歪了,通常是环境没对齐。
- 字体差异:本地Windows有微软雅黑、宋体,服务器没有。
- 库版本差异:
package-lock.json或requirements.txt没锁死,服务器装了新版。 - 临时目录差异:本地
/tmp权限宽松,服务器受限。 - 时区/编码:服务器
LANG不是en_US.UTF-8或zh_CN.UTF-8,中文路径可能出错。 - CPU架构:ARM服务器上某些二进制依赖需要重新编译。
解决思路就两条:用Docker把字体和依赖打包进镜像,或者用配置管理工具把服务器环境写成脚本,别手动一台台改,改完下次又忘。
开源库和商业库怎么选:服务器生成pdf免费库和付费库对比
先看下表再决定,别一上来就买授权。
| 方案 | 成本 | 适合场景 | 注意点 |
|---|---|---|---|
| wkhtmltopdf | 免费 | 常规报表、HTML转PDF | 老引擎,复杂CSS支持有限 |
| Puppeteer/Playwright | 免费 | 现代网页、前端渲染复杂 | 内存占用较高,需装系统依赖 |
| TCPDF/FPDF | 免费 | 纯PHP生成简单PDF | 中文需手动加字体 |
| iText | 商业授权 | 复杂分页、PDF表单、合规场景 | 商用需购买license |
| PDFKit | 免费 | Node.js轻量生成 | 复杂表格需自己算坐标 |
预算有限时,先把开源方案调通,真遇到开源库搞不定的分页、签名、PDF/A合规,再评估商业库,别为了省小钱把生成服务拖垮。
云服务器pdf生成服务配置教程:从依赖装到代码调
基础环境准备清单
以Ubuntu 22.04为例,按顺序执行:
apt update apt install -y fonts-wqy-zenhei fonts-wqy-microhei fc-cache -fv
如果跑Puppeteer,还要补运行库:
apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libxss1 libasound2 libgbm1
内存建议至少2GB;生成复杂长报表时,4GB更稳。磁盘预留空间不低于5GB,临时文件比你想的占地。
常见生成库的配置要点
- Puppeteer:启动参数加
--no-sandbox --disable-setuid-sandbox,容器内更要注意executablePath指向正确Chromium。 - wkhtmltopdf:本地文件访问要开
--enable-local-file-access,页面尺寸用--page-size A4,边距用--margin-top 10mm这种明确参数。 - Java iText:字体文件放固定路径,代码里注册;注意AGPL/商业授权边界,别把试用当免费。
- Python WeasyPrint:依赖
pango、cairo,缺库时直接报cannot load library,按官方文档装系统包即可。
权限与路径检查步骤
- 建专用运行用户,别用root跑生成服务。
- 输出目录属主改成运行用户,例如
chown -R www-data:www-data /data/pdf。 - 检查
/tmp权限是否为1777,被改坏就恢复。 - 如果开了SELinux,先看
ausearch -m avc -ts recent有没有拦截写文件。
服务器生成pdf速度慢怎么优化?别只盯着CPU
硬件瓶颈排查
先跑三条命令:
free -h vmstat 1 5 iostat -x 1 5
si/so持续非零,说明内存在换页,加内存比换CPU有用。%util接近100%,磁盘IO是瓶颈,考虑把临时目录挂到SSD。- CPU的
wa很高,多数是在等IO。
业内专家指出,PDF生成服务卡顿更多来自内存和临时文件IO,而不是单纯算力不够。
代码层优化
- 复用浏览器实例:Puppeteer每次
launch开销很大,改成连接池或长驻浏览器。 - 减少外部请求:把字体、CSS、Logo放到本地或内网,避免生成时等外网。
- 异步队列:生成任务丢进队列,前端拿任务ID轮询,别让HTTP请求干等。
- 控制并发:按内存算,2GB机器并发别超过2个。
分页与图片处理
- 大表格先分页再渲染,别把几万行一次性塞进HTML。
- 图片提前压缩,生成时设置合理DPI,300DPI够印刷,屏幕展示150DPI就够。
- 超时时间别设太短,复杂页面给30秒到60秒,同时加失败重试。
服务器生成PDF常见问题Q&A
Q1:服务器生成PDF提示字体未找到,本地却正常,为什么?
本地系统自带中文字体,服务器最小化安装通常没有,用fc-list :lang=zh确认,装wqy-zenhei或wqy-microhei后执行fc-cache -fv,再重启生成服务。
Q2:云服务器生成PDF偶尔超时,怎么判断是网络还是资源问题?
先看dmesg -T | grep -i oom和free -h,有OOM就是内存问题;再看应用日志里是否卡在加载外部CSS/字体,把外部资源改成本地路径后仍超时,多半是页面太大或并发太高。
Q3:服务器生成PDF免费库和付费库到底选哪个?
常规报表、HTML转PDF优先用wkhtmltopdf或Puppeteer,零授权成本;需要复杂分页、PDF表单填写、数字签名或商用合规时,再评估iText商业授权,多数中小项目先用开源方案验证,跑不通再换,这是事实上的通行做法。
首发原创文章,作者:王坚,如若转载,请注明出处:https://idctop.com/article/804069.html


