如何排查Next.js构建时‘类型检查与代码扫描’步骤耗时超20分钟问题？

一、npm run build类型检查阶段的具体操作 #

Next.js的npm run build中，"Linting and checking validity of types"步骤本质是调用TypeScript的tsc --noEmit命令，对整个项目的所有TypeScript/JavaScript文件（包括导入的JSON文件）执行全量类型校验：

• 解析所有导入模块的类型定义
• 推导变量、函数、组件的类型兼容性
• 检查类型断言、泛型、接口的合法性
• 配合ESLint（若启用）执行代码风格与类型相关的规则检查

二、查看详细检查日志的方法 #

• 执行详细日志模式的build命令：

  npm run build -- --verbose
  # 或直接用Next.js命令
  next build --verbose
  

  该命令会输出TypeScript检查的每一步细节，能看到具体卡在哪个文件或类型计算环节。
• 单独运行TypeScript检查：跳过完整build，直接执行类型校验并查看性能诊断：

  # 查看详细检查日志
  npx tsc --noEmit --verbose
  # 查看性能报告（关键！能定位耗时文件）
  npx tsc --noEmit --diagnostics
  

三、可能的核心原因 #

1. JSON自动类型推导的“类型爆炸”：5MB的深层嵌套JSON，TypeScript会自动生成极其复杂的嵌套类型（可能包含数百层递归或数千个字段），类型检查器需要消耗大量CPU和内存来处理这些复杂类型，导致耗时剧增。
2. 复杂类型断言/泛型的连锁计算：如果在getServerSideProps中对JSON数据添加了自定义的深层嵌套类型断言或泛型，会触发TypeScript的递归类型推导，进一步加重计算负担。
3. ESLint规则的额外消耗：若项目启用了typescript-eslint的严格规则（比如@typescript-eslint/no-unused-vars的全量检查、@typescript-eslint/explicit-module-boundary-types），这些规则在处理复杂类型时会额外消耗大量时间。
4. 潜在的无限循环类型：如果自定义类型中存在循环引用（比如类型A依赖类型B，类型B又依赖类型A），会让TypeScript陷入无限递归的类型计算。

四、调试与解决建议 #

• 先确认问题来源：临时在next.config.js中禁用类型检查，验证是否是该环节导致的耗时：

  module.exports = {
    typescript: {
      ignoreBuildErrors: true,
    },
  };
  

  若build能快速完成，即可锁定是类型检查的问题。
• 手动简化JSON类型定义：不要依赖TypeScript自动推导JSON的复杂类型，手动定义仅包含你实际用到的字段的接口，用类型断言跳过自动推导：

  // 只定义业务需要的字段，而非全量JSON结构
  interface RequiredData {
    targetSection: {
      key: string;
      value: number;
    };
  }
  
  export async function getServerSideProps() {
    // 用unknown中转后断言为自定义简化类型
    const rawData = await import('./large-data.json');
    const data = rawData as unknown as RequiredData;
    // 仅提取需要的字段传递给组件，避免传递复杂类型
    const props = { neededData: data.targetSection };
    return { props };
  }
  

• 拆分大JSON文件：将5MB的JSON拆分为多个小文件，按需导入，减少单次类型推导的复杂度。
• 优化TypeScript配置：在tsconfig.json中调整参数降低检查负担：

  {
    "compilerOptions": {
      "skipLibCheck": true, // 跳过第三方库的类型检查
      "incremental": true, // 启用增量编译（对重复build有帮助）
      "strictNullChecks": false // 临时关闭严格空检查，测试是否提速
    }
  }
  

• 排查无限循环类型：检查所有自定义类型接口/类型别名，确认是否存在循环引用的情况，比如：

  // 错误示例：循环引用导致类型计算无限循环
  type TypeA = { b: TypeB };
  type TypeB = { a: TypeA };
  

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