1. 问题现象与背景分析最近在做一个Next.js项目时遇到了一个让人头疼的问题使用Sharp库在Vercel生产环境将SVG转为PNG时中文字符全部变成了乱码。这个现象特别有意思因为在本地开发环境一切正常只有部署到Vercel后才会出现。具体表现是生成的PNG图片中英文和数字显示正常但中文字符变成了类似口口口的方块或者显示为Unicode码位。这个问题直接影响到了我们项目中需要动态生成带中文的图片功能比如分享卡片、预览图等场景。经过反复测试和排查我发现问题的根源在于Vercel的服务器环境缺少中文字体支持。Sharp库在转换SVG到PNG时需要依赖系统字体来渲染文本。本地开发环境通常都安装了完整的中文字体但Vercel的轻量级容器环境默认只包含基本英文字体。2. 问题原因深度解析2.1 Sharp库的字体处理机制Sharp底层使用libvips进行图像处理它依赖于系统的Fontconfig来管理和加载字体。当处理包含文本的SVG时Sharp会解析SVG中的文本元素根据font-family属性查找可用字体使用找到的字体渲染文本到图像在Vercel环境中这个流程在第三步出了问题。因为默认容器没有中文字体Fontconfig找不到匹配的字体就会回退到基本字体导致中文无法正确渲染。2.2 开发与生产环境的差异为什么本地没问题而生产环境有问题这涉及到几个关键差异字体安装开发者本地机器通常安装了完整字体集而Vercel服务器是精简环境字体缓存Vercel的只读文件系统导致Fontconfig无法创建字体缓存环境配置生产环境缺少必要的字体配置文件查看Vercel的日志你会看到类似Fontconfig error: No writable cache directories的错误这证实了我们的判断。3. 完整解决方案3.1 准备字体文件首先需要获取支持中文的字体文件。我推荐使用开源的Noto Sans SC字体它完美支持简体中文在项目根目录创建fonts文件夹从Noto字体官网下载Regular字重的TTF文件将文件重命名为NotoSansSC-Regular.ttf并放入fonts文件夹3.2 配置Fontconfig在fonts文件夹下创建fonts.conf文件内容如下?xml version1.0? !DOCTYPE fontconfig SYSTEM fonts.dtd fontconfig dir/var/task/fonts//dir cachedir/tmp/fonts-cache//cachedir config/config /fontconfig这个配置文件做了三件事指定字体搜索目录设置可写的缓存目录提供基本的Fontconfig配置3.3 修改SVG生成代码确保你的SVG模板正确指定了字体族function getSvgBuffer({ text }) { const svg svg width800 height400 text x50% y50% font-familyNoto Sans SC, sans-serif font-size40 text-anchormiddle dominant-baselinemiddle ${text} /text /svg ; return Buffer.from(svg, utf-8); }关键点是font-family属性要包含我们添加的中文字体。3.4 设置环境变量在项目根目录创建.env文件FONTCONFIG_PATH/var/task/fonts然后在Vercel的项目设置中也要添加同样的环境变量。这个变量告诉Fontconfig去哪里找配置文件。4. 部署与验证完成以上步骤后重新部署到Vercel。部署时需要注意确保fonts文件夹和其中的文件被打包到部署产物中检查Vercel的环境变量是否设置正确部署后查看构建日志确认没有字体相关的错误测试时可以尝试生成包含中文的图片观察是否正常显示。如果仍有问题可以通过Vercel的日志功能进一步排查。5. 其他注意事项5.1 字体文件大小考量Noto Sans SC常规字重的TTF文件大约15MB这对部署包大小是个挑战。有几种优化方案使用子集字体只包含项目实际用到的字符从CDN加载字体部署时不打包字体运行时下载选择更小的中文字体如思源黑体、阿里巴巴普惠体5.2 多语言支持如果需要支持多种语言如简体中文繁体中文日文可以使用Noto Sans CJK系列字体它们设计统一能完美混排。5.3 字体缓存优化在Vercel的无服务器环境中每次冷启动都需要重新加载字体。可以通过以下方式优化将字体缓存放在/tmp目录使用Sharp的缓存配置考虑使用Edge Functions减少冷启动6. 替代方案评估除了使用系统字体还有其他几种解决中文乱码的方法将文字转为路径使用工具将SVG中的文字转为路径这样就不需要字体支持。缺点是失去文本可编辑性。使用Canvas渲染先用Canvas绘制文字和图形再转为PNG。这种方法更灵活但实现复杂。服务端渲染在Node.js服务器上安装完整字体。适合有自主服务器的场景不适用于Vercel。经过对比添加字体文件仍然是最可靠、最直接的解决方案特别是在Vercel这样的托管平台上。7. 常见问题排查在实际使用中可能会遇到以下问题问题1部署后仍然显示乱码检查字体文件路径是否正确确认环境变量已设置并生效查看Vercel日志是否有字体相关错误问题2构建时间显著增加字体文件较大可能导致构建变慢考虑将字体放在单独的层或使用CDN问题3部分特殊字符仍不正常确认字体文件包含这些字符检查SVG的编码声明是否为UTF-8遇到这些问题时Sharp的GitHub issues和Vercel的文档都是很好的参考资源。