如何搭建兼容react-scripts@5.0.1与typescript@^5的React包生态？

问题根源 #

react-scripts@5.0.1的peer依赖规则明确限定TypeScript版本为^3.2.1 || ^4，直接安装TS 5.2.2+会触发peer依赖冲突；而使用--legacy-peer-deps仅能跳过版本校验，无法解决react-scripts内部工具链（如ESLint插件、类型校验逻辑）对TS 5.x的适配问题，因此会出现类型无法识别的情况。

解决方案 #

1. 升级react-scripts到支持TS 5.x的版本 #

这是最稳妥的方案，react-scripts后续版本（如v5.1.0及以上）已更新peer依赖，支持TypeScript 5.x。执行以下命令：

# 升级react-scripts到最新稳定版
npm install react-scripts@latest

# 安装指定版本的TypeScript
npm install typescript@>=5.2.2

升级完成后，peer依赖冲突会自动解决，类型识别也能正常工作。

2. 强制安装TS 5.x（临时应急方案） #

如果暂时无法升级react-scripts，可使用--force参数强制安装TS 5.x，它会忽略peer依赖冲突并覆盖版本校验：

npm install typescript@>=5.2.2 --force

⚠️ 注意：此方法可能引发构建流程中的未知兼容性问题（如ESLint报错、编译异常），仅建议作为短期临时方案，后续优先升级react-scripts。

3. 替换为更灵活的构建工具（长期优化方案） #

若react-scripts的版本限制成为项目长期瓶颈，建议替换为原生支持TS 5.x的构建工具，比如：

• Vite：轻量快速，原生支持TS，配置简洁
• Next.js：内置TS支持，适合React全栈项目
• 自定义Webpack配置：完全掌控构建流程，适配任意TS版本

以Vite迁移为例，步骤如下：

# 卸载react-scripts
npm uninstall react-scripts

# 安装Vite及React插件
npm install vite @vitejs/plugin-react

创建vite.config.js配置文件：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

修改package.json中的脚本命令：

{
  "scripts": {
    "start": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

最后重新安装TS 5.2.2+即可正常运行项目。

为什么--legacy-peer-deps无效？ #

--legacy-peer-deps仅能跳过npm的peer依赖版本检查，但不会修改react-scripts内部工具链的TS版本适配逻辑。react-scripts@5.0.1配套的ESLint插件、TypeScript校验工具仅针对TS 4.x及以下版本开发，无法识别TS 5.x的新语法或类型定义，因此会出现类型无法识别的报错。

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