Next.js Dev环境正常 Build后访问详情页报500错误排查

报错核心触发逻辑如下：

1. Node.js 17及以上版本默认将localhost域名优先解析为IPv6回环地址::1，而Next.js 12.1.6版本执行next start启动生产服务时，默认仅监听IPv4回环地址127.0.0.1的3000端口，未绑定IPv6回环地址，因此服务端发起fetch('http://localhost:3000/xxx.json')请求时，会尝试连接::1:3000直接触发连接拒绝。
2. 开发环境执行next dev时默认同时监听IPv4、IPv6双栈地址，因此不会触发该问题，这也是开发、生产环境表现不一致的核心原因。
3. 测试过的SSG、SSR两种数据获取模式的执行逻辑均跑在服务端/构建阶段，只要内部包含指向localhost的fetch请求，就会触发相同错误，和选用的渲染模式无关。
4. 网传删除swcMinify: true的方案是针对Next.js客户端水合不匹配报错的，和当前网络连接类错误无关联，无需关注该配置。

• 最优方案（推荐）：移除服务端对本地静态资源的HTTP请求
  public目录下的静态文件本身存放在项目本地，在getStaticProps/getStaticPaths/getServerSideProps这类服务端执行的方法中，完全不需要发起HTTP请求读取，直接通过Node.js原生文件系统接口读取即可，从根源上规避网络解析、端口监听类问题：

  // 示例代码，放在对应数据获取方法内
  import fs from 'fs'
  import path from 'path'
  // 读取public目录下的对应商品JSON文件
  const filePath = path.join(process.cwd(), 'public', 'products', `${params.id}.json`)
  const productData = JSON.parse(fs.readFileSync(filePath, 'utf8'))
  

  该方案无额外依赖、读取性能更好，不会受部署环境的网络配置影响。

• 快速修复方案：强制使用IPv4地址发起请求
  如果暂时不想重构文件读取逻辑，直接将代码中所有fetch请求的http://localhost:3000替换为http://127.0.0.1:3000，强制Node.js走IPv4回环地址连接服务，绕过localhost的IPv6默认解析逻辑，改造成本极低，修改后重新构建即可生效。

• 配置层修复方案：调整生产服务监听地址
  修改package.json中的生产启动命令，强制Next.js启动时绑定IPv6栈，兼容双地址访问：

  {
    "scripts": {
      "start": "next start -H ::"
    }
  }
  

  该方案不需要修改业务代码，但需要保证部署环境支持IPv6回环，适配性弱于前两个方案。

修改完成后重新执行npm run build构建，再执行npm run start启动生产服务，点击商品列表项跳转详情页即可正常加载，浏览器不再返回500错误，终端也不会抛出TypeError: fetch failed异常。

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