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 version="1.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 width="800" height="400"> <text x="50%" y="50%" font-family="'Noto Sans SC', sans-serif" font-size="40" text-anchor="middle" dominant-baseline="middle" > ${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的文档都是很好的参考资源。
