Next.js使用ENV变量配置Image组件时的水合不匹配问题

原因分析 #

这个水合不匹配的核心问题是环境变量在客户端未被正确注入：

• Next.js 默认仅将带NEXT_PUBLIC_前缀的环境变量暴露给客户端代码；不带该前缀的变量仅能在服务端（Node.js 环境）中读取。
• 你定义的STRAPIHOST没有前缀，因此服务端渲染时能正常获取值并生成完整图片 URL；但客户端浏览器运行时无法读取该变量，process.env.STRAPIHOST变为undefined，拼接后出现undefined/xxx.svg的错误路径，与服务端渲染内容不匹配，触发水合警告。

解决方案 #

1. 修改环境变量命名 #

在你的.env或.env.local文件中，给环境变量添加NEXT_PUBLIC_前缀：

NEXT_PUBLIC_STRAPIHOST=http://localhost:1337

2. 更新图片路径拼接函数 #

同步修改函数中的变量引用：

interface ImageProp {
    data: {
        attributes: {
            url: string,
        }
    }
}

export function strapiImage(src: ImageProp) {
    return process.env.NEXT_PUBLIC_STRAPIHOST + src.data.attributes.url;
}

3. 可选：增加健壮性处理 #

为避免环境变量未配置时出现异常，可以添加空值判断：

export function strapiImage(src: ImageProp) {
    const baseUrl = process.env.NEXT_PUBLIC_STRAPIHOST || '';
    return `${baseUrl}${src.data.attributes.url}`;
}

4. 重启开发服务 #

修改环境变量后，必须重启 Next.js 开发服务器，确保新的环境变量被加载生效。

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