Golang PDF服务构建Docker镜像后提示找不到NanumGothic字体文件求助

排查步骤与解决方案 #

1. 确认镜像内实际存在字体文件 #

首先执行命令验证容器内对应路径下的文件是否存在：

docker run --rm <替换为你的镜像名称> ls -lh /go/src/pdf.server/templates/font/

如果输出中没有对应字体文件，排查以下两点：

• 检查项目根目录的.dockerignore文件是否排除了templates/目录或.ttf后缀文件，部分Docker版本复制不存在的源文件时不会报错，仅会创建空目录
• 确认构建上下文匹配：COPY指令中开头带斜杠的源路径是相对于docker build执行时的工作目录，确认执行构建的目录下确实存在templates/font/NanumGothic-Regular.ttf文件
• 如果本地的字体文件是软链接，COPY指令默认只会复制软链接本身，不会关联实际文件，可改用COPY --follow-link参数复制源文件

2. 校验目录权限 #

gofpdf的AddUTF8Font方法会默认在字体同目录生成.z后缀的缓存文件，如果程序运行用户对字体目录没有写权限，旧版本的gofpdf会误报字体文件不存在，而非权限错误。可以在Dockerfile中新增权限配置：

RUN chmod -R 755 /go/src/pdf.server/templates/font/

也可以调用pdf.SetFontCacheDir()方法，将缓存目录指定到程序有写权限的路径，避免修改字体目录权限。

3. 排查多阶段构建遗漏 #

如果使用多阶段构建，确认复制字体的COPY指令是写在最终运行镜像的阶段，而非仅在构建二进制的阶段，避免构建阶段的文件未被打包到最终运行镜像中。

4. 验证路径拼接逻辑 #

你报错的路径显示为相对路径go/src/pdf.server/...而非预期的绝对路径/go/src/pdf.server/...，可以临时在读取字体的代码前增加日志，打印os.Getenv("GOPATH")和拼接后的fontDir全路径，确认和容器内实际路径一致。

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