解决Next.js + Sharp在Vercel环境下SVG转PNG的中文乱码问题

1. 问题现象与背景分析

最近在做一个Next.js项目时，遇到了一个让人头疼的问题：使用Sharp库在Vercel生产环境将SVG转为PNG时，中文字符全部变成了乱码。这个现象特别有意思，因为在本地开发环境一切正常，只有部署到Vercel后才会出现。

具体表现是：生成的PNG图片中，英文和数字显示正常，但中文字符变成了类似"口口口"的方块，或者显示为Unicode码位。这个问题直接影响到了我们项目中需要动态生成带中文的图片功能，比如分享卡片、预览图等场景。

经过反复测试和排查，我发现问题的根源在于Vercel的服务器环境缺少中文字体支持。Sharp库在转换SVG到PNG时，需要依赖系统字体来渲染文本。本地开发环境通常都安装了完整的中文字体，但Vercel的轻量级容器环境默认只包含基本英文字体。

2. 问题原因深度解析

2.1 Sharp库的字体处理机制

Sharp底层使用libvips进行图像处理，它依赖于系统的Fontconfig来管理和加载字体。当处理包含文本的SVG时，Sharp会：

1. 解析SVG中的文本元素
2. 根据font-family属性查找可用字体
3. 使用找到的字体渲染文本到图像

在Vercel环境中，这个流程在第三步出了问题。因为默认容器没有中文字体，Fontconfig找不到匹配的字体，就会回退到基本字体，导致中文无法正确渲染。

2.2 开发与生产环境的差异

为什么本地没问题而生产环境有问题？这涉及到几个关键差异：

• 字体安装：开发者本地机器通常安装了完整字体集，而Vercel服务器是精简环境
• 字体缓存：Vercel的只读文件系统导致Fontconfig无法创建字体缓存
• 环境配置：生产环境缺少必要的字体配置文件

查看Vercel的日志，你会看到类似"Fontconfig error: No writable cache directories"的错误，这证实了我们的判断。

3. 完整解决方案

3.1 准备字体文件

首先需要获取支持中文的字体文件。我推荐使用开源的Noto Sans SC字体，它完美支持简体中文：

1. 在项目根目录创建fonts文件夹
2. 从Noto字体官网下载Regular字重的TTF文件
3. 将文件重命名为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。部署时需要注意：

1. 确保fonts文件夹和其中的文件被打包到部署产物中
2. 检查Vercel的环境变量是否设置正确
3. 部署后查看构建日志，确认没有字体相关的错误

测试时，可以尝试生成包含中文的图片，观察是否正常显示。如果仍有问题，可以通过Vercel的日志功能进一步排查。

5. 其他注意事项

5.1 字体文件大小考量

Noto Sans SC常规字重的TTF文件大约15MB，这对部署包大小是个挑战。有几种优化方案：

1. 使用子集字体：只包含项目实际用到的字符
2. 从CDN加载字体：部署时不打包字体，运行时下载
3. 选择更小的中文字体：如思源黑体、阿里巴巴普惠体

5.2 多语言支持

如果需要支持多种语言（如简体中文+繁体中文+日文），可以使用Noto Sans CJK系列字体，它们设计统一，能完美混排。

5.3 字体缓存优化

在Vercel的无服务器环境中，每次冷启动都需要重新加载字体。可以通过以下方式优化：

1. 将字体缓存放在/tmp目录
2. 使用Sharp的缓存配置
3. 考虑使用Edge Functions减少冷启动

6. 替代方案评估

除了使用系统字体，还有其他几种解决中文乱码的方法：

1. 将文字转为路径：使用工具将SVG中的文字转为路径，这样就不需要字体支持。缺点是失去文本可编辑性。

2. 使用Canvas渲染：先用Canvas绘制文字和图形，再转为PNG。这种方法更灵活但实现复杂。

3. 服务端渲染：在Node.js服务器上安装完整字体。适合有自主服务器的场景，不适用于Vercel。

经过对比，添加字体文件仍然是最可靠、最直接的解决方案，特别是在Vercel这样的托管平台上。

7. 常见问题排查

在实际使用中，可能会遇到以下问题：

问题1：部署后仍然显示乱码

• 检查字体文件路径是否正确
• 确认环境变量已设置并生效
• 查看Vercel日志是否有字体相关错误

问题2：构建时间显著增加

• 字体文件较大可能导致构建变慢
• 考虑将字体放在单独的层或使用CDN

问题3：部分特殊字符仍不正常

• 确认字体文件包含这些字符
• 检查SVG的编码声明是否为UTF-8

遇到这些问题时，Sharp的GitHub issues和Vercel的文档都是很好的参考资源。