如何在Heroku上为WeasyPrint配置自定义字体处理日语字符

我之前在Heroku上部署WeasyPrint处理多语言内容时，也碰到过日语字符显示方框的问题——本质就是Heroku默认环境没有预装日语字体，加上WeasyPrint需要的系统依赖没配置到位。下面是我亲测有效的解决步骤：

步骤1：添加日语字体到项目 #

• 下载一款支持完整日语字符的开源字体，比如Noto Sans JP（Google出品，覆盖所有常用日语字符）
• 在项目根目录新建一个fonts文件夹，把下载的字体文件（比如NotoSansJP-Regular.otf）放入其中，确保这个文件夹能被Git追踪（不要在.gitignore里排除它）

步骤2：修改CSS引入自定义字体 #

更新你的CSS代码，用@font-face声明字体，然后指定页面元素使用该字体：

@font-face {
    font-family: 'Noto Sans JP';
    src: url('fonts/NotoSansJP-Regular.otf') format('opentype');
    font-weight: normal;
    font-style: normal;
}
h1, body {
    font-family: 'Noto Sans JP', sans-serif;
}

步骤3：配置Heroku的系统依赖 #

WeasyPrint依赖一些底层系统库才能在Heroku上正常运行，你需要在项目根目录创建一个Aptfile，内容如下：

libpango-1.0-0
libpangocairo-1.0-0
libcairo2
libgdk-pixbuf2.0-0
libffi-dev
shared-mime-info

同时确保requirements.txt里包含WeasyPrint的依赖：

weasyprint>=59.0

步骤4：调整Python代码 #

把CSS整合到你的代码中，确保FontConfiguration能正确识别自定义字体：

from weasyprint import HTML, CSS
from weasyprint.fonts import FontConfiguration

font_config = FontConfiguration()
# 这里的字体路径要和项目内的实际路径一致
css = CSS(string="""
@font-face {
    font-family: 'Noto Sans JP';
    src: url('fonts/NotoSansJP-Regular.otf') format('opentype');
    font-weight: normal;
    font-style: normal;
}
h1 {
    font-family: 'Noto Sans JP', sans-serif;
}
""", font_config=font_config)

html = HTML(string='<h1>Title here 自家製フォント工房</h1>')
html.write_pdf(
    'report.pdf',
    stylesheets=[css],
    font_config=font_config
)

额外注意事项 #

• 如果使用其他日语字体，只需要替换@font-face中的文件名和路径即可
• 部署前先在本地测试修改后的代码，确认字体正常显示后再推送到Heroku
• 确保字体文件的相对路径在Heroku上有效（Heroku会完整部署你的项目文件，本地路径正常的话线上也会正常）

内容的提问来源于stack exchange，提问作者Ahmed Farahat