---
title: Linux 下 wkhtmltopdf 中文乱码或空白处理
description: Odoo 打印 PDF 依赖 wkhtmltopdf，系统源版本常低于 0.12.0，且缺中文字体会导致乱码或空白。本文说明适用场景、准备与风险、安装与字体配置步骤、验证方法、回退建议及常见问题，参数均用占位符表示。
url: "https://www.lanever.com/docs/linux-%e4%b8%8b-wkhtmltopdf-%e4%b8%ad%e6%96%87%e4%b9%b1%e7%a0%81%e6%88%96%e7%a9%ba%e7%99%bd%e5%a4%84%e7%90%86/"
updated: "2026-10-12"
category: Odoo
---

# Linux 下 wkhtmltopdf 中文乱码或空白处理

> **参考来源与致谢**
>
>
>
> - **引用来源：**[linux 安装 wkhtmltopdf 中文乱码或者空白解决方法 - 阳光雨露 - ITeye技术网站](http://huqiji.iteye.com/blog/2278225)
> - **原作者：**原页面署名作者或发布机构（剪藏记录未保存可核验的个人署名）
> - **感谢词：**感谢原作者及发布机构对技术知识的公开分享。本文已结合企业运维场景完成脱敏、核验与原创重写，并非原文转载；如权利人需要更正署名或来源信息，请联系本站。

## 适用场景

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 验证。

## 验证方法

1. 执行 `wkhtmltopdf -V` 确认版本符合要求。
2. 用本地 HTML 文件生成 PDF，检查是否成功输出。
3. 在 Odoo 客户端触发一次报表打印，确认不再提示缺少 wkhtmltopdf。
4. 打开生成的 PDF，检查中文是否正常显示，无空白或方框。

```
wkhtmltopdf [本地HTML文件] [输出PDF路径]
```

## 回退建议

- 若新版本异常，恢复备份的旧可执行文件到 `/usr/bin/`，并恢复原权限。
- 若字体配置引发问题，移除新增字体文件后执行 `fc-cache -fv`。
- 回退后重启 Odoo 服务，再次验证打印功能。

## 常见问题

- **提示版本过低：**发行版源版本不满足要求，需更换来源，具体支持范围查阅对应版本官方文档。
- **PDF 中文空白或方框：**服务器缺少中文字体，安装字体并刷新缓存后重试。
- **命令找不到：**确认可执行文件位于系统路径且具备可执行权限。
- **生成失败：**检查依赖库是否齐全，必要时查阅官方文档的依赖说明。
