react-scripts v5.0.1不兼容TypeScript v5？CRA项目迁移TS如何解决？

背景 #

我有一个用CRA创建的2年历史的项目，正尝试迁移至TypeScript，当前package.json的相关依赖如下：

"@testing-library/jest-dom": "^5.16.4",
"@testing-library/react": "^13.3.0",
"@testing-library/user-event": "^13.5.0",
"@types/jest": "^29.5.3",
"@types/node": "^20.5.0",
"@types/react": "^18.2.20",
"@types/react-dom": "^18.2.7",
...
"react": "^18.2.0",
"react-dom": "^18.2.0",
...
"typescript": "^5.1.6",
"web-vitals": "^2.1.4"

我用AWS CodeBuild编译该项目，配置文件如下：

version: 0.2

phases:
  install:
    commands:
      - npm ci
  build:
    commands:
      - npm run build
      
artifacts:
  files:
    - '**/*'
  base-directory: 'build'

执行编译时出现依赖冲突错误，核心信息是react-scripts v5.0.1不支持TypeScript 5.x版本，仅兼容3.x或4.x版本，完整错误日志如下：

[Container] 2023/08/16 18:34:54 Running command npm ci 
npm ERR! code ERESOLVE 
npm ERR! ERESOLVE could not resolve 
npm ERR!  
npm ERR! While resolving: react-scripts@5.0.1 
npm ERR! Found: typescript@5.1.6 
npm ERR! node_modules/typescript 
npm ERR!   typescript@"^5.1.6" from the root project 
npm ERR!   peer typescript@">= 2.7" from fork-ts-checker-webpack-plugin@6.5.2 
npm ERR!   node_modules/fork-ts-checker-webpack-plugin 
npm ERR!     fork-ts-checker-webpack-plugin@"^6.5.0" from react-dev-utils@12.0.1 
npm ERR!     node_modules/react-dev-utils 
npm ERR!       react-dev-utils@"^12.0.1" from react-scripts@5.0.1 
npm ERR!       node_modules/react-scripts 
npm ERR!         react-scripts@"^5.0.1" from the root project 
npm ERR!   1 more (tsutils) 
npm ERR!  
npm ERR! Could not resolve dependency: 
npm ERR! peerOptional typescript@"^3.2.1 || ^4" from react-scripts@5.0.1 
npm ERR! node_modules/react-scripts 
npm ERR!   react-scripts@"^5.0.1" from the root project 
npm ERR!  
npm ERR! Conflicting peer dependency: typescript@4.9.5 
npm ERR! node_modules/typescript 
npm ERR!   peerOptional typescript@"^3.2.1 || ^4" from react-scripts@5.0.1 
npm ERR!   node_modules/react-scripts 
npm ERR!     react-scripts@"^5.0.1" from the root project 
npm ERR!  
npm ERR! Fix the upstream dependency conflict, or retry 
npm ERR! this command with --force or --legacy-peer-deps 
npm ERR! to accept an incorrect (and potentially broken) dependency resolution. 
npm ERR!  
npm ERR! For a full report see: 
npm ERR! /root/.npm/_logs/2023-08-16T18_35_12_328Z-eresolve-report.txt 
npm ERR! A complete log of this run can be found in: 
npm ERR!     /root/.npm/_logs/2023-08-16T18_35_12_328Z-debug-0.log

疑问 #

react-scripts是否不再支持TypeScript？我想在CRA项目中使用TypeScript，应该怎么做？

1. 明确：react-scripts依然支持TypeScript，仅存在版本兼容限制 #

react-scripts v5.0.1的peer依赖明确要求TypeScript版本为^3.2.1 || ^4，不兼容TypeScript 5.x。这不是停止支持，而是版本匹配规则导致的冲突。

2. 方案一：降级TypeScript到兼容版本 #

修改package.json中的TypeScript版本为4.x系列的最新稳定版（如4.9.5）：

"typescript": "^4.9.5"

然后执行以下命令重新安装依赖：

rm package-lock.json
npm ci

此方案能彻底解决依赖冲突，保证项目稳定编译。

3. 方案二：使用--legacy-peer-deps跳过依赖检查 #

若不想降级TypeScript，可在npm命令中添加--legacy-peer-deps参数忽略peer依赖冲突，修改AWS CodeBuild的install阶段配置：

install:
  commands:
    - npm ci --legacy-peer-deps

注意：该方式可能引入潜在兼容性问题，需先在本地测试项目构建及运行正常后再使用。

4. 方案三：升级react-scripts到支持TypeScript 5.x的版本 #

若后续react-scripts发布支持TypeScript 5.x的版本，可直接升级react-scripts：

npm install react-scripts@latest

升级后需检查其他依赖的兼容性，做好项目测试。

5. 方案四：eject项目或迁移至替代构建工具 #

若长期需要使用最新版TypeScript且不想受限于react-scripts的版本限制，可选择：

• 执行npm run eject暴露CRA底层配置，手动修改webpack等配置以适配TypeScript 5.x，但eject后无法再接收CRA官方更新。
• 迁移至Vite等现代化构建工具，这类工具对最新TypeScript版本支持更及时，且构建速度更快。

内容的提问来源于stack exchange，提问作者Young Jun Joo