参考来源与致谢
- 引用来源:linux 安装 wkhtmltopdf 中文乱码或者空白解决方法 – 阳光雨露 – ITeye技术网站
- 原作者:原页面署名作者或发布机构(剪藏记录未保存可核验的个人署名)
- 感谢词:感谢原作者及发布机构对技术知识的公开分享。本文已结合企业运维场景完成脱敏、核验与原创重写,并非原文转载;如权利人需要更正署名或来源信息,请联系本站。
适用场景 #
Odoo(含早期 OpenERP)在打印报表时若提示缺少 wkhtmltopdf,只能以 HTML 预览,通常说明服务端未安装该工具,或已安装版本低于 Odoo 要求。部分发行版软件源提供的版本较旧,可能不满足最低版本要求。另有一类现象是 PDF 能生成,但中文显示为空白或方框,多与服务器缺少中文字体有关。
本文面向企业 IT 运维,给出通用处理思路。不同 Odoo 版本对 wkhtmltopdf 的最低版本要求不同,请以对应版本官方文档为准。
准备与风险 #
- 确认 Odoo 版本及其官方文档中要求的 wkhtmltopdf 最低版本。
- 准备测试环境,先在测试服务器验证,再操作生产环境。
- 备份当前 wkhtmltopdf 可执行文件及字体目录,便于回退。
- 记录当前版本:
wkhtmltopdf -V。 - 下载来源应为可信渠道,校验文件完整性后再安装。
- 替换系统二进制文件属于变更操作,建议在维护窗口进行。
涉及覆盖系统文件或安装第三方二进制包时,务必先备份并确认回退路径。
处理步骤 #
1. 检查现有版本 #
wkhtmltopdf -V
若版本低于 Odoo 要求,需升级。若发行版源内版本过旧,可考虑使用官方提供的预编译包,具体可用版本请查阅对应官方文档。
2. 安装或替换二进制文件 #
下载与服务器架构匹配的预编译包(32 位或 64 位),解压后将其中的可执行文件放置到系统路径。
tar -vxf [压缩包文件名]
sudo cp wkhtmltox/bin/wkhtmltopdf /usr/bin/
sudo chown root:root /usr/bin/wkhtmltopdf
sudo chmod +x /usr/bin/wkhtmltopdf
如系统已存在旧版本,覆盖前先备份原文件。
3. 配置中文字体 #
若生成的 PDF 中文为空白或方框,说明服务器缺少可用中文字体。可从已授权环境获取中文字体文件,复制到字体目录并刷新缓存。
sudo cp [中文字体文件] /usr/share/fonts/
sudo fc-cache -fv
字体文件需确保授权允许在服务器使用。刷新后重新生成 PDF 验证。
验证方法 #
- 执行
wkhtmltopdf -V确认版本符合要求。 - 用本地 HTML 文件生成 PDF,检查是否成功输出。
- 在 Odoo 客户端触发一次报表打印,确认不再提示缺少 wkhtmltopdf。
- 打开生成的 PDF,检查中文是否正常显示,无空白或方框。
wkhtmltopdf [本地HTML文件] [输出PDF路径]
回退建议 #
- 若新版本异常,恢复备份的旧可执行文件到
/usr/bin/,并恢复原权限。 - 若字体配置引发问题,移除新增字体文件后执行
fc-cache -fv。 - 回退后重启 Odoo 服务,再次验证打印功能。
常见问题 #
- 提示版本过低:发行版源版本不满足要求,需更换来源,具体支持范围查阅对应版本官方文档。
- PDF 中文空白或方框:服务器缺少中文字体,安装字体并刷新缓存后重试。
- 命令找不到:确认可执行文件位于系统路径且具备可执行权限。
- 生成失败:检查依赖库是否齐全,必要时查阅官方文档的依赖说明。
