React-Typescript项目构建遇graphql TS版本兼容错误（已用TS^5.5.3）

问题重现 #

执行构建命令tsc -b && vite build时出现编译错误：

> sdt-global-ui@0.0.0 build
> tsc -b && vite build

node_modules/graphql/NotSupportedTSVersion.d.ts:1:63 - error TS1003: Identifier expected.

1 "Package 'graphql' support only TS versions that are >=4.1.0".

Found 1 error.

依赖链路显示graphql是@vitest/browser@2.1.2 → msw@2.4.9的子依赖，当前TS版本为^5.5.3，需保留@vitest/browser。

原因分析 #

graphql@16.9.0的NotSupportedTSVersion.d.ts文件存在语法错误：它直接写入提示字符串而非合法TypeScript语法，导致TS编译器报错。你的TS版本远高于该包要求的>=4.1.0，错误完全由该文件本身的写法问题导致。

解决方案 #

方案1：强制升级graphql到兼容版本（推荐） #

通过npm的overrides或yarn的resolutions强制将子依赖的graphql替换为修复了该问题的版本（16.10.0及以上）：

• 若使用npm，在package.json中添加：

  "overrides": {
    "graphql": "^16.10.0"
  }
  

• 若使用yarn，在package.json中添加：

  "resolutions": {
    "graphql": "^16.10.0"
  }
  

执行npm install或yarn install后，重新运行构建命令即可。

方案2：排除错误的声明文件 #

在tsconfig.json的exclude数组中添加该错误文件，让TS编译时忽略它：

{
  "compilerOptions": {
    // 你的编译配置
  },
  "exclude": [
    "node_modules",
    "node_modules/graphql/NotSupportedTSVersion.d.ts"
  ]
}

方案3：临时修改错误文件（不推荐） #

直接修改node_modules/graphql/NotSupportedTSVersion.d.ts的内容为合法注释：

// Package 'graphql' support only TS versions that are >=4.1.0

注意：此方法会在每次执行npm install时被覆盖，仅适合临时测试。

验证 #

修改后重新执行tsc -b && vite build，确认错误消失。

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