Next.js项目运行报错：TypeError: fetch failed及证书验证问题求助

问题描述 #

• 操作流程：搭建Next.js项目后，在项目目录执行npm run dev命令
• 报错信息：

TypeError: fetch failed
    at node:internal/deps/undici/undici:12618:11
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async getVersionInfo (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\dev\hot-reloader-webpack.js:215:21)
    at async Span.traceAsyncFn (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\trace\trace.js:154:20)
    at async HotReloaderWebpack.start (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\dev\hot-reloader-webpack.js:607:28)
    at async startWatcher (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\lib\router-utils\setup-dev-bundler.js:156:5)
    at async setupDevBundler (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\lib\router-utils\setup-dev-bundler.js:775:20)
    at async Span.traceAsyncFn (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\trace\trace.js:154:20)
    at async initialize (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\lib\router-server.js:78:30)    
    at async Server.<anonymous> (D:\Study\WebDev\My Projects\vtu\node_modules\next\dist\server\lib\start-server.js:249:36) {
  cause: Error: unable to verify the first certificate
      at TLSSocket.onConnectSecure (node:_tls_wrap:1674:34)
      at TLSSocket.emit (node:events:518:28)
      at TLSSocket._finishInit (node:_tls_wrap:1085:8)
      at ssl.onhandshakedone (node:_tls_wrap:871:12) {
    code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
  }
}

• 补充信息：使用Next.js 14.2.2版本，已尝试设置npm config set strict-ssl true但问题未解决

解决思路与建议 #

错误核心是UNABLE_TO_VERIFY_LEAF_SIGNATURE，说明Node.js在执行fetch请求（此处为Next.js热重载模块获取版本信息）时无法验证SSL证书链，以下是针对性解决方案：

• 临时禁用SSL证书验证（仅开发环境）
  启动命令添加环境变量跳过证书验证，注意仅用于开发场景，生产环境禁止使用：

  NODE_TLS_REJECT_UNAUTHORIZED=0 npm run dev
  

• 配置Node.js信任自定义CA证书
  若处于公司内网或使用自定义CA证书，需将CA证书加入Node.js信任列表：

  1. 获取CA证书文件（Windows可通过certmgr.msc导出，Linux可从/etc/ssl/certs目录获取）
  2. 启动时指定证书路径：

     NODE_EXTRA_CA_CERTS=/path/to/your/ca-cert.pem npm run dev
     

  或在项目根目录.env.local文件中添加环境变量：

  NODE_EXTRA_CA_CERTS=/path/to/your/ca-cert.pem
  

• 检查并调整npm代理配置
  若使用代理，可能是代理证书导致验证失败：

  • 查看当前代理设置：npm config get proxy、npm config get https-proxy
  • 配置代理证书：npm config set cafile /path/to/proxy-cert.pem
  • 临时取消代理：npm config delete proxy、npm config delete https-proxy

• 升级Node.js版本
  部分旧版本Node.js的undici（Next.js依赖的fetch实现）存在证书验证bug，建议升级至Node.js LTS版本（如20.x或18.x最新版）后重试。

• 清除项目缓存
  清理旧缓存文件避免残留问题：
  Linux/macOS：

  rm -rf .next node_modules package-lock.json
  npm install
  npm run dev
  

  Windows：

  Remove-Item -Recurse -Force .next, node_modules, package-lock.json
  npm install
  npm run dev
  

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