
同一份报表,本机导出中文正常,放进Linux服务器或容器后却变成方框。先别把整份文件转成图片:需要确认的是,输入文字是否正确、生成进程能否取得所需字体,以及最终PDF怎样保存和显示这些字形。
这篇针对“你能控制生成服务”的情况,给出定位顺序。它不意味着装一个字体包就能修复所有PDF,也不涉及给已经损坏的原文件补回未知文字。
选一段明确知道内容的文字,比如“采购报价,设备编号0017,金额0.00元”。保留中文、编号和零值,避免只用英文标题判断整个文件正常。
依次保留三份材料:传入生成器的HTML或数据、生成后的PDF、目标环境中的显示结果。
观察到的现象 | 优先检查 | 还不能直接下的结论 |
|---|---|---|
HTML或请求数据已经乱码 | 编码、模板读取、数据传递 | 不能先归因于PDF字体 |
输入正确,仅部署后出现方框或缺字 | 字体资源、字形覆盖、读取权限和渲染配置 | 不能只凭现象认定未嵌入字体 |
PDF看着正常,复制后文字异常 | 文本编码映射、提取方式 | 安装字体不一定能修复复制结果 |
换阅读器或机器打开同一份PDF,是缩小问题范围的方法。两个阅读器都异常,并不能单独证明“字体未嵌入”;字体缺少目标字形、映射错误或文件内容异常,也需要考虑。

图:排查路径示意,不能只凭单个现象认定原因。
开发机上有某种中文字体,不代表Linux容器内也有。宿主机有字体,也不代表容器或服务账号能读取。
在运行服务的容器或主机中,可先检查:
# 需要环境中已有 fontconfig 工具
fc-list :lang=zh family file这可以查看fontconfig登记的中文字体,不能代替生成组件自身的字体注册结果。若SDK通过指定目录加载字体,应继续确认目录已进入部署包、进程可读,而且所选字体包含实际要使用的字符。
也要核对字体族名称和字体文件名。把CSS写成一个不存在的字体族,不能靠“目录里刚好有一个ttf文件”保证选中它。字体的安装、使用和嵌入授权也应在分发前确认。
以ComPDF Generation for Java为例,其字体管理文档提供字体目录、系统字体和字体提供器的配置方式。
在已完成SDK集成和许可初始化的Layout API项目里,可把字体目录作为部署配置明确传入,而不是假定所有机器的系统字体相同:
// 字体注册片段:放入已初始化的 Layout API 文档构建流程。
// document 和 div 为当前文档及内容元素,下面不是完整程序。
CFontProvider fonts = new CFontProvider();
fonts.addDirectory("/app/fonts");
document.setFontProvider(fonts);
div.setFontFamily("Noto Sans CJK SC");/app/fonts和字体族名称需要换成项目中实际部署、已获准使用的字体。实际效果仍需在目标容器与所选字体上确认。采用其他组件时,也应使用该组件自己的注册机制。
HTML生成路径与Layout API不能照搬同一段文档调用。ComPDF的HTML生成配置通过CConverterProperties设置字体提供器,页面尺寸、资源基准路径等也在相应转换流程配置。请按当前SDK版本选择对应路径,不能把document.setFontProvider直接当作HTML转换入口。
若环境中有Poppler工具,可用下面的命令查看结果文件的字体条目:
pdffonts output.pdf重点看字体名称及emb嵌入状态,但不要把任何一个字段当成“文件一定正确”的证明。emb=yes仍需核对实际中文字形;emb=no提示需进一步检查字体依赖和生成配置,不等于所有阅读器都会立即显示失败。
再用目标阅读器打开最终文件,确认中文、数字、负号及标点,尝试搜索和复制关键文字;有打印要求时,还需核对实际打印或目标打印路径。普通页面正常,也不能证明生僻字、粗体和其他语言都正常。
最小样例通过后,用一份实际有代表性的报表检查长表格、粗体、罕见字符和分页,再回归批量任务。保留字体资源版本、组件版本和原始输入,便于后续部署出现差异时对照。
如果你已经使用Java生成服务,可以先按上面的字体配置文档补齐明确的资源加载路径;如果仍在选择HTML模板还是Layout API,则先确定模板和版式由谁维护,再评估相应接入方式。ComPDF承担文档生成,字体分发、运行账号权限和业务数据正确性仍需由项目落实。
最终要交付的不是“服务器装了中文字体”,而是一份在实际使用环境中能正确阅读、搜索和使用的PDF。先确认输入正确,再确认生成进程取得了正确字体,最后核对最终文件,才能知道问题改在了哪一层。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。