Next.js从AWS S3加载静态图片时未生成哈希且无法走CDN

解决方案 #

1. 验证assetPrefix的生效环境 #

assetPrefix仅在生产构建模式（执行next build && next start）下生效，开发环境（next dev）会忽略该配置。如果当前是开发环境测试，看不到CDN路径属于正常情况，需构建生产版本验证效果。

2. 配置Image组件的CDN域名（关键步骤） #

Next.js的Image组件对public目录下的资源有独立的域名校验机制，需在next.config.js中添加images.domains配置，指定CDN域名，否则Image组件不会自动拼接assetPrefix：

const getCDN = () => {
  if (process.env.NEXT_PUBLIC_APP_ENV === 'staging') {
    return 'https://cdn.staging.mydomain.com.au/';
  }

   if (process.env.NEXT_PUBLIC_APP_ENV === 'production') {
    return 'https://cdn.mydomain.com/';
  }
};

const getImageDomain = () => {
  if (process.env.NEXT_PUBLIC_APP_ENV === 'staging') {
    return 'cdn.staging.mydomain.com.au';
  }

   if (process.env.NEXT_PUBLIC_APP_ENV === 'production') {
    return 'cdn.mydomain.com';
  }
};

module.exports = {
  assetPrefix: getCDN(),
  images: {
    domains: [getImageDomain()],
    // Next.js 13+ App Router 默认启用优化，无需额外配置；若需关闭优化可设置unoptimized: true，但不建议
    // unoptimized: false
  },
}

配置后，Image组件会自动将src={'images/logo.png'}转换为带哈希的CDN路径。

3. 确认资源上传路径匹配 #

构建后，哈希后的静态资源存放在本地.next/static/media目录，上传到S3时需保证路径完全对应：

• 本地文件：.next/static/media/logo.68a3dfc9.png
• S3目标路径：_next/static/media/logo.68a3dfc9.png
  最终CDN访问路径应为：https://cdn.mydomain.com/_next/static/media/logo.68a3dfc9.png

4. 检查环境变量是否正确注入 #

确保NEXT_PUBLIC_APP_ENV环境变量在构建阶段已正确设置，否则getCDN()会返回undefined，导致assetPrefix不生效。可在构建前执行echo $NEXT_PUBLIC_APP_ENV验证变量值。

5. 字体资源的自动处理 #

对于public/fonts下的字体文件，只需在CSS中正常引用即可，Next.js会自动将路径转换为带哈希的CDN路径：

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom-font.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
}

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