Next.js执行npm run build时类型错误的原因及解决方法

错误成因 #

1. Props类型不匹配：Next.js执行npm run build时会对页面组件的props做严格校验，当页面组件（如Home）通过getServerSideProps/getStaticProps获取数据，同时组件自身接收额外props（如Success组件的id）时，若未正确合并页面props类型与组件props类型，会触发内部OmitWithTag类型工具的校验失败。
2. 类型约束冲突：错误提示中的{ [x: string]: never; }表示Next期望页面组件除数据获取方法返回的props外，不应有未声明的额外属性，但你的SuccessProps中的id属性未被纳入页面props的类型体系，且id的类型被推断为any（后端返回的string未被正确映射），导致与never类型的索引签名冲突。
3. 开发与build校验差异：本地开发时Next的类型校验较为宽松，不会触发严格的props合并校验，因此开发阶段无报错，但build时会执行完整的类型检查，暴露问题。

解决方案 #

1. 合并页面Props与组件Props类型 #

定义页面组件的完整Props类型，将数据获取方法返回的PageProps与组件所需的SuccessProps合并：

// 假设PageProps是你的数据获取方法返回的类型
type HomePageProps = PageProps & SuccessProps;

// 让Home组件接收合并后的类型
export default function Home(props: HomePageProps) {
  return <Success id={props.id} />;
}

2. 明确SuccessProps的类型定义 #

确保id的类型为明确的string，避免被推断为any：

type SuccessProps = {
  id: string;
};

3. 规范数据获取方法的返回类型 #

在getServerSideProps/getStaticProps中，确保返回的id类型与SuccessProps匹配，可通过类型断言明确类型：

export async function getServerSideProps() {
  const res = await fetch('你的后端接口地址');
  const data = await res.json();
  
  return {
    props: {
      // 明确id为string类型
      id: data.id as string,
    },
  };
}

4. 移除不必要的Omit操作 #

若之前手动使用Omit类型处理页面props，直接使用合并后的完整类型即可，Next会自动处理props的传递与校验，无需手动剔除属性。

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