参考来源与致谢
- 引用来源:Odoo14打印PDF中文显示乱码解决方法 | Junle's Blog
- 原作者:原页面署名作者或发布机构(剪藏记录未保存可核验的个人署名)
- 感谢词:感谢原作者及发布机构对技术知识的公开分享。本文已结合企业运维场景完成脱敏、核验与原创重写,并非原文转载;如权利人需要更正署名或来源信息,请联系本站。
适用场景 #
Odoo 14 在打印报价单、发票、采购单等 PDF 报表时,中文字符显示为方块、空白或乱码,而网页界面中文正常。此类问题多出现在 Linux 服务器部署环境,尤其是最小化安装或容器镜像中未预装中文字体的情况。
本文适用于自建服务器或容器化部署的 Odoo 14 运维场景。不同发行版、不同部署方式(源码、包管理、容器)的字体路径与重启方式存在差异,具体请以对应版本官方文档为准。
准备与风险 #
- 确认当前 Odoo 版本与部署方式,记录服务启动命令与配置文件路径。
- 确认服务器可访问软件源,或已准备离线字体包。
- 变更前对数据库与自定义报表模板做备份,并在测试环境先行验证。
- 安装字体与重启服务属于可逆操作,但重启会中断当前会话,建议安排在维护窗口执行。
- 若使用容器部署,需确认字体安装是否会被镜像重建覆盖,必要时写入镜像构建流程。
处理步骤 #
1. 检查现有字体 #
先确认系统是否已存在中文字体,避免重复安装。
fc-list :lang=zh
若无输出或输出为空,说明缺少中文字体。
2. 安装中文字体 #
在 Debian/Ubuntu 系发行版上,可安装常见开源中文字体包。以下命令为通用形式,包名请以实际软件源为准:
sudo apt-get update
sudo apt-get install ttf-wqy-zenhei
sudo apt-get install ttf-wqy-microhei
其他发行版请使用对应的包管理工具安装同类字体。若服务器无法联网,可下载字体文件后放入系统字体目录,例如 /usr/share/fonts/ 下的自定义子目录。
3. 刷新字体缓存 #
安装完成后刷新字体缓存,使新字体对系统可见:
sudo fc-cache -fv
再次执行 fc-list :lang=zh 确认字体已被识别。
4. 重启 Odoo 服务 #
PDF 渲染进程通常在服务启动时加载字体,需重启 Odoo 服务使其生效。重启命令依部署方式而定,例如 systemd 管理时可使用:
sudo systemctl restart [Odoo服务名]
容器部署时重启对应容器即可。重启前请确认无正在执行的关键任务。
验证方法 #
- 登录 Odoo,进入任一含中文的报表,例如报价单或发票。
- 点击打印,选择 PDF 输出。
- 打开生成的 PDF,检查中文标题、字段值与表头是否正常显示。
- 可同时验证多个报表模板,排除单一模板问题。
若仍显示异常,检查报表模板是否指定了不含中文字形的字体,必要时在模板中改用已安装字体。
回退建议 #
- 若变更后出现异常,可卸载新增字体包并刷新缓存,再重启服务。
- 若问题与模板修改相关,使用变更前的模板备份恢复。
- 容器环境可回退到变更前的镜像标签。
- 回退后重新验证 PDF 输出,确认系统恢复至变更前状态。
常见问题 #
安装字体后仍乱码 #
可能原因:字体缓存未刷新、服务未重启、报表模板指定了其他字体、容器内未实际安装字体。建议逐项排查。
网页正常但 PDF 异常 #
网页由浏览器渲染,PDF 由服务器端渲染,两者字体来源不同。服务器缺少中文字体时,通常只影响 PDF。
能否直接复制字体文件 #
可以,但需放入系统字体目录并刷新缓存,同时注意字体授权许可。
不同版本处理方式是否一致 #
字体安装与缓存刷新属系统层操作,思路通用;但服务重启方式与模板机制可能随版本变化,请查阅对应版本官方文档。
提示:生产环境变更前务必完成备份与测试环境验证,避免影响正常业务。
