Next.js Image组件remotePatterns环境变量生产环境失效问题排查

问题详情 #

本地开发阶段，无论用环境变量还是直接写死字符串配置Image组件的remotePatterns，都能正常加载图片；但部署到生产环境后，用环境变量配置就会导致图片加载失败，换成硬编码字符串则显示正常。已确认服务器环境变量值正确，相关代码如下：

// nextConfig 
const nextConfig = {
    reactStrictMode: true,
    env: {
        NEXT_PUBLIC_DOMAIN: process.env.NEXT_PUBLIC_DOMAIN,
    },
    async rewrites() {
        return {
            fallback: [
                {
                    source: "/:path*",
                    destination: `${process.env.NEXT_PUBLIC_DOMAIN}/:path*`,
                },
            ],
        };
    },
    images: {
        remotePatterns: [
            {
                protocol: "https",
                hostname: `${process.env.NEXT_PUBLIC_PLATFORM_HOSTNAME}`,
                port: "",
                pathname: `${process.env.NEXT_PUBLIC_API_URL}/image/**`,
            },
        ],
    },
};

module.exports = nextConfig;

// partial file
export const BASE_PLATFORM_IMAGE_SRC = `https://${process.env.NEXT_PUBLIC_PLATFORM_HOSTNAME}${process.env.NEXT_PUBLIC_API_URL}/image/vendor`;

 <Image
    className="rounded-lg object-cover text-white"
    fill // fill container
    src={`${BASE_PLATFORM_IMAGE_SRC}/${id}/publicity/3`}
    alt={t(props.i18n)}
/>

问题原因 #

核心原因是Next.js的remotePatterns属于构建时配置：

• 生产环境部署前会执行预构建打包，这个过程中Next.js会把remotePatterns的配置固化到产物里。如果你的环境变量是在运行时才注入（比如部署平台仅设置了运行时变量，没在构建阶段传入），构建过程中根本读不到变量值，导致remotePatterns的hostname和pathname配置为空或错误，生产环境自然无法匹配图片的远程域名，进而加载失败。
• 本地开发时Next.js是热重载模式，会实时读取环境变量，不管是构建时还是运行时变量都能生效，所以不会出现问题。

解决方法 #

• 确保环境变量在构建阶段传入：用Vercel、Netlify等部署平台时，要在项目的「构建环境变量」中配置NEXT_PUBLIC_PLATFORM_HOSTNAME和NEXT_PUBLIC_API_URL，而非仅设置运行时变量。如果是自己搭建服务器，要在执行npm run build命令前先导出这些环境变量。
• 简化变量引用：变量本身就是字符串类型，直接使用process.env.NEXT_PUBLIC_PLATFORM_HOSTNAME即可，不需要额外用模板字符串包裹，修改后的remotePatterns示例：

  images: {
      remotePatterns: [
          {
              protocol: "https",
              hostname: process.env.NEXT_PUBLIC_PLATFORM_HOSTNAME,
              port: "",
              pathname: `${process.env.NEXT_PUBLIC_API_URL}/image/**`,
          },
      ],
  },
  

• 验证构建时变量有效性：可以在构建脚本中添加打印命令，比如echo $NEXT_PUBLIC_PLATFORM_HOSTNAME，确认构建过程中能拿到正确的变量值。
• 检查变量前缀：确保所有需要在构建配置和客户端使用的环境变量都带有NEXT_PUBLIC_前缀，Next.js只会暴露带该前缀的变量到构建流程和客户端代码中。

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