Django使用xhtml2pdf生成PDF时格鲁吉亚文字显示黑块怎么解决？
2026-9-27
Django xhtml2pdf 生成PDF格鲁吉亚文字显示黑块问题排查与解决
根本原因
该问题是xhtml2pdf默认内置字体不包含格鲁吉亚语字符集，缺少对应字符的字形，渲染时就会显示为黑块或空白占位符，和编码配置无关（你的代码里已经正确指定了utf-8编码）。
排查步骤
- 先验证HTML渲染结果是否正常：注释视图中pisa生成PDF的代码，直接返回渲染后的
html变量到浏览器，查看格鲁吉亚文字是否正常显示，若此处乱码先排查模板编码、数据库字符集配置，若正常则100%是字体问题。 - 验证字体兼容性：确认你使用的字体明确支持格鲁吉亚语字符，推荐使用开源的DejaVu系列字体，全系列原生支持格鲁吉亚语。
具体解决步骤
准备字体文件
下载支持格鲁吉亚语的字体（比如DejaVuSans.ttf），放到Django项目的静态资源目录，例如static/fonts/DejaVuSans.ttf。修改PDF模板的CSS配置
在你用到的test.html模板的<head>标签内添加以下CSS，声明自定义字体并全局指定使用该字体：
<style> @font-face { font-family: 'DejaVuSans'; src: url('/absolute/path/to/your/project/static/fonts/DejaVuSans.ttf'); /* 这里建议写字体文件的绝对文件系统路径，避免xhtml2pdf读取静态资源路径失败 */ } /* 全局强制使用该字体，避免部分元素继承默认字体 */ * { font-family: 'DejaVuSans' !important; } </style>
- 修复视图代码的已知错误
你现有视图代码中get_object_or_404(id, pk=pk)写法错误，第一个参数需要传入你要查询的模型类，假设你的模型名为Customer，修改为：
customer = get_object_or_404(Customer, pk=pk)
修改完成后重新生成PDF，格鲁吉亚文字即可正常显示。
备选方案
如果xhtml2pdf字体配置多次尝试无效，可以换用对非拉丁字符支持更好的weasyprint库替换xhtml2pdf，配置逻辑更简单，对复杂CSS的兼容性也更好。
内容的提问来源于stack exchange，提问作者Zura Begadze
相关产品推荐
相关产品推荐
