Next.js getStaticProps请求本地API执行next build报错问题

API 探路者

2026-8-28

核心原因

不要在getStaticProps、getStaticPaths这类静态构建阶段执行的方法中，通过HTTP请求调用本地项目的Next.js API路由。
Next.js API路由本身属于服务端接口，需要Next服务完全启动后才会监听端口响应请求，而next build执行静态页面生成的阶段，Next服务并未处于对外提供服务的状态，此时请求http://localhost:3000必然会出现连接拒绝错误。
你尝试提前启动服务再执行构建触发的EPERM权限报错，是因为两个Next进程同时抢占读写.next构建目录，触发了文件锁冲突，本质上构建时请求本地API这个思路本身就不符合Next.js的设计逻辑。

正确实现方案

结合你只需要生成3个静态页面、且API返回内容为固定静态数据的场景，直接按以下方式改造即可，完全不需要走HTTP请求：

抽离公共数据逻辑：把API路由里的数据查询、组装逻辑抽离到独立的公共服务文件中，比如新建lib/page-data.js，在这个文件里直接定义数据、或者直接操作数据库/读取本地文件获取数据，不需要套API路由的HTTP层：

// lib/page-data.js
const pageConfig = {
  cs: {
    headerText: "Page Header text",
    joinText: "Some text",
    benefits: [
      {
        src: "/cs/photo-1.webp",
        text: "Some text",
      },
      {
        src: "/cs/photo-2.webp",
        text: "some text",
      },
    ],
    advisor: {
      name: "Name",
      email: "person-email",
      linkedin: "https://www.linkedin.com/in/person",
    },
    advisorMsg: "Some text",
  },
  hyd: {
    // 对应hyd页面的配置内容
  },
  cass: {
    // 对应cass页面的配置内容
  }
}

export async function getData(id) {
  // 后续如果需要改成读数据库、读本地markdown文件，直接在这里改逻辑即可
  return pageConfig[id]
}

复用逻辑改造API路由：原来的API路由不需要删除，直接引入抽离好的getData方法即可，避免重复写数据逻辑：

// pages/api/[id].js
import { getData } from '../../lib/page-data'

export default async function handler(req, res) {
  const data = await getData(req.query.id)
  res.status(200).json(data)
}

页面侧getStaticProps直接引入公共方法调用：不需要再发fetch请求，直接走服务端内部函数调用，构建阶段会直接执行拿到数据，不会有任何网络请求相关的报错：

// pages/[id].js
import { getData } from '../lib/page-data'

export async function getStaticProps({ params }) {
  const data = await getData(params.id);
  return {
    props: {
      data,
    },
  };
}

export async function getStaticPaths() {
  return {
    paths: [
      { params: { id: "cs" } },
      { params: { id: "hyd" } },
      { params: { id: "cass" } },
    ],
    fallback: false,
  };
}

注意事项

getStaticProps内的代码只会在构建阶段的服务端环境执行，代码不会被打包到客户端侧JS中，可以放心在抽离的getData方法里直接连接数据库、读取服务端本地文件，不需要通过API路由做中转。
如果你的接口逻辑强依赖用户请求上下文（比如需要读取cookie、请求头做鉴权），那这类逻辑本身就不适合在静态生成阶段执行——静态生成是构建时批量生成页面，不存在真实用户的请求上下文，这类场景建议改成客户端侧请求数据，或者改用getServerSideProps做服务端渲染。
不要尝试用“提前启动服务再构建”的方式绕开连接错误，这种方式不仅会因为文件锁触发权限问题，还会拖慢构建速度，容易出现开发环境和生产构建行为不一致的问题。

内容的提问来源于stack exchange，提问作者Mohammed Rehan