Next.js 14项目构建失败与启动报错问题求助

关于替换localhost为process.env.LOCALHOST的可行性 #

完全可行，这是规范环境变量管理的合理做法，能避免硬编码地址带来的环境适配问题。具体操作：

1. 在项目根目录创建.env文件，添加配置：LOCALHOST=http://localhost:你的服务端口号（如果请求的是本地API，需填写对应API服务端口）
2. 在代码中替换fetch('http://localhost:xxx/xxx')为fetch(${process.env.LOCALHOST}/xxx)
3. 注意：如果是服务器组件中的fetch，无需给变量加NEXT_PUBLIC_前缀；如果是客户端组件需要访问该变量，才需要改为NEXT_PUBLIC_LOCALHOST

核心问题分析与解决办法 #

你的两个报错是关联的：ECONNREFUSED导致构建失败，进而未生成.prerender-manifest.json，最终npm run start报错。优先解决预渲染阶段的fetch失败问题：

1. 预渲染fetch失败的根源 #

Next.js 14构建时会预渲染指定页面（如/、/AllCourses），如果页面的服务器组件/getStaticProps中包含对本地localhost服务的fetch请求，而构建时该服务未启动，就会出现ECONNREFUSED错误。

2. 针对性解决办法 #

• 方案一：构建前启动依赖服务
  如果fetch目标是本地API，在执行npm run build前先启动你的API服务（比如npm run start:api），确保构建时请求能正常连接。

• 方案二：构建阶段返回模拟数据
  通过Next.js提供的process.env.NEXT_PHASE环境变量判断当前是否处于构建阶段，返回模拟数据替代真实请求：

  async function getCourses() {
    if (process.env.NEXT_PHASE === 'phase-production-build') {
      // 构建阶段返回模拟数据
      return [
        { id: 1, name: 'Mock Course 1' },
        { id: 2, name: 'Mock Course 2' }
      ];
    }
    // 非构建阶段发起真实请求
    const res = await fetch(`${process.env.LOCALHOST}/api/courses`);
    return res.json();
  }
  

• 方案三：调整预渲染策略
  对于依赖动态数据的页面，改用增量静态再生（ISR）或服务器组件动态渲染，避免构建时强制预渲染：

  • App Router中，在页面组件添加export const revalidate = 60;（每60秒重新生成页面）
  • Pages Router中，使用getServerSideProps替代getStaticProps，让页面在请求时渲染而非构建时

3. 解决.prerender-manifest.json缺失问题 #

当构建成功完成后，Next.js会自动生成.prerender-manifest.json文件。只要解决了预渲染阶段的fetch错误，重新执行npm run build，该文件就会正常生成，npm run start的报错也会消失。

4. 其他排查与修复步骤 #

• 清理构建缓存：执行以下命令彻底清理缓存后重新安装依赖并构建：

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

• 核对Node.js版本：Next.js 14要求Node.js版本≥18.17.0或≥20.6.0，确保你的版本符合要求（执行node -v查看）
• 检查Next.js配置：确认next.config.js中的basePath、rewrites等配置未导致路由或请求路径错误

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