Laravel+Inertia+React构建报错：找不到scheduler/tracing模块及类型声明

问题背景 #

使用Node 20.13.1 + NPM 10.8.0开发Laravel+Inertia+React应用，npm run dev运行正常，但执行npm run build时触发TypeScript错误：

node_modules/@types/react/index.d.ts:41:53 - error TS2307: Cannot find module 'scheduler/tracing' or its corresponding type declarations.

41 import { Interaction as SchedulerInteraction } from 'scheduler/tracing';

解决方案 #

1. 安装scheduler的类型依赖 #

scheduler是React内部依赖，但TypeScript类型包可能未自动安装，手动补充：

npm install @types/scheduler --save-dev

2. 调整TypeScript配置跳过库类型检查 #

在项目根目录的tsconfig.json中，给compilerOptions添加skipLibCheck配置，跳过第三方库的类型检查，快速规避该错误：

{
  "compilerOptions": {
    // 其他配置...
    "skipLibCheck": true
  }
}

3. 锁定scheduler版本匹配React #

React 18.2.0对应依赖的scheduler版本为0.23.2，手动安装该版本确保兼容性：

npm install scheduler@0.23.2 --save

4. 强制统一依赖版本 #

若存在依赖冲突，在package.json中添加overrides字段强制所有依赖使用指定的scheduler版本：

{
  // 其他配置...
  "overrides": {
    "scheduler": "0.23.2"
  }
}

添加后重新执行npm install。

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