部署Next.js至Vercel时遇TypeScript与@types/react未识别问题

云上老周

2026-7-8

解决Next.js部署Vercel时提示缺少TypeScript与@types/react的问题

检查Vercel构建配置与缓存
先查看Vercel控制台部署日志里的依赖安装环节，确认npm install（或你使用的包管理器）是否正常拉取了typescript和@types/react。如果日志里无这两个包的安装记录，直接在部署设置里开启「Disable Build Cache」，强制重新安装所有依赖后再触发部署。另外要确认构建命令为标准的next build，避免自定义命令绕开正常的依赖检测流程。
排查cheerio引发的依赖冲突
本地执行npm ls typescript和npm ls @types/react，查看输出是否存在版本冲突——cheerio的间接依赖可能引入了不同版本的TypeScript，导致Vercel构建时依赖解析混乱。如果发现冲突，在package.json里添加overrides字段锁定版本：
```
"overrides": {
  "typescript": "5.1.6",
  "@types/react": "18.2.15"
}
```
之后删除node_modules、package-lock.json，本地重新安装依赖再推送代码。
验证TypeScript配置正确性
打开tsconfig.json，确认compilerOptions.types里包含react，或者是否开启了skipLibCheck导致类型检查逻辑异常。同时检查next.config.js里是否存在异常的TypeScript相关配置，比如typescript: { ignoreBuildErrors: true }可能干扰Vercel的依赖检测。
对齐本地与Vercel的环境
确保Vercel使用的包管理器与本地一致（比如本地用npm就不要让Vercel自动切换为pnpm），在部署设置里指定包管理器版本。另外核对本地Node.js版本和Vercel配置的Node版本，版本差异也可能导致依赖安装出现问题。