Docker容器中文PDF生成解决方案

迷失蒲公英2025-08-05 22:21

在Docker容器中生成包含中文内容的PDF文件时，经常遇到中文字符显示为方块或乱码的问题。本文将详细介绍如何在Docker环境中配置中文字体支持，实现完美的中文PDF生成。

问题现象

当使用wkhtmltopdf、Puppeteer或其他PDF生成工具时：

中文字符显示为方块 □□□
字体回退到默认字体，样式不符合预期
PDF文件大小异常或生成失败

解决方案

1. 安装中文字体支持

在Docker镜像中安装中文字体是解决问题的关键步骤。详细的字体安装方法请参考：
CentOS及Debian安装字体教程

2. 配置PDF生成工具

javascript 复制代码

// wkhtmltopdf配置示例
const options = {
  format: 'A4',
  orientation: 'portrait',
  border: {
    top: '1cm',
    right: '1cm',
    bottom: '1cm',
    left: '1cm'
  },
  // 指定中文字体
  'default-encoding': 'utf-8',
  'enable-local-file-access': null
};

3. Dockerfile最佳实践

dockerfile 复制代码

FROM node:16-alpine

# 安装字体依赖 - 详见字体安装教程
RUN apk add --no-cache \
    fontconfig \
    ttf-dejavu \
    wkhtmltopdf

# 复制中文字体文件
COPY fonts/*.ttf /usr/share/fonts/truetype/
RUN fc-cache -fv

# 应用程序配置
WORKDIR /app
COPY . .
RUN npm install

EXPOSE 3000
CMD ["npm", "start"]

常见问题排查

字体未生效：检查字体文件路径和权限
容器体积过大：选择必要的字体文件
性能问题：优化字体缓存配置

总结

通过正确安装中文字体和配置PDF生成工具，可以完美解决Docker容器中的中文PDF生成问题。关键是要确保字体文件正确安装并被系统识别。