Next.js执行yarn build时静态图片触发fetch failed编译报错

第一步：修正静态资源引用路径（90%的同类报错都是这个问题） #

next dev模式下自带路径兜底兼容，路径写错也可能正常加载，但生产构建是严格静态分析，路径写法不对直接触发fetch资源失败。

• 所有放在public目录下的文件，引用时绝对不能带public前缀，也不要写多层相对路径跳去public目录找文件，更不要写localhost开头的本地URL当资源地址。
  下面这些都是开发能跑、构建必炸的错误写法，挨个对照你自己的Contact.jsx、Projects.jsx、pages/index.js里的代码改：

  // 错误1：导入路径带public前缀
  import contactImg from '../public/assets/contact.jpg'
  // 错误2：写相对路径跨层级找public下的图片
  <img src="../../public/assets/projects/property.jpg" />
  // 错误3：给本地图片写localhost的绝对地址
  <Image src="http://localhost:3000/assets/contact.jpg" />
  

  正确写法非常简单：public目录就是你站点的根路径，直接写斜杠开头的资源路径就行，不需要import：

  // 普通img标签
  <img src="/assets/contact.jpg" alt="联系我们" />
  // next/image组件（记得补width/height或者fill属性，不然也会构建报错）
  import Image from 'next/image'
  <Image 
    src="/assets/projects/property.jpg" 
    alt="房产项目展示" 
    width={800} 
    height={600} 
  />
  

  之前写的import public资源的语句直接删掉就行，public目录的资源构建时会自动托管，不需要webpack打包处理，强行import反而会让构建程序尝试去拉取文件触发fetch错误。

第二步：修正next.config.js图片优化配置 #

如果你用了next/image组件，去检查next.config.js里的images配置，下面两种错配也会导致构建拉取图片失败：

// 错误配置示例
const nextConfig = {
  images: {
    loader: 'akamai/cloudinary/其他第三方加载器', // 强制指定第三方加载器后，本地图片会被当做远端资源拉取直接失败
    domains: ['localhost'], // 生产构建阶段localhost根本不是可访问的有效域名，拉取直接报错
  }
}

修复方式：没接第三方图片存储服务就删掉loader配置，domains数组里只保留你实际用到的外站图片域名，不要加localhost。

第三步：清缓存+排查环境问题 #

如果路径和配置都改对了还是报错，按顺序操作：

• 清缓存重装依赖：执行下面的命令删掉旧的构建产物、依赖和锁文件，重装后再构建

  rm -rf .next node_modules yarn.lock
  yarn install
  yarn build
  

• 检查Node版本：Next.js 12要求Node版本≥14.18.0，Next.js 13及以上要求Node≥16.14.0，版本过低会导致构建阶段内置fetch API兼容报错，直接升级到Node 18/20 LTS版本即可。
• 临时关闭系统代理/VPN：构建阶段如果系统开了全局代理，本地资源请求会被代理拦截，直接报fetch failed，关了代理再跑build命令。

验证 #

改完后执行yarn build，构建成功后跑yarn start访问本地3000端口，确认两个图片都能正常加载就没问题，可以正常部署。

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