使用Vite部署至Vercel时遇TS2688错误：找不到vite/client类型定义

问题重现 #

部署时遇到的错误：

error TS2688: Cannot find type definition file for 'vite/client'.
  The file is in the program because:
    Entry point of type library 'vite/client' specified in compilerOptions
Error: Command "npm run build" exited with 2

当前客户端tsconfig.json配置：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    },
    "target": "ESNext",
    "useDefineForClassFields": true,
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "allowJs": false,
    "skipLibCheck": true,
    "esModuleInterop": false,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "types": ["vite/client"]
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

解决方案 #

• 重新同步Vite依赖
  本地执行命令重新安装Vite，确保依赖版本正确写入配置文件，再提交到仓库：

  npm install vite --save-dev
  

• 调整TypeScript类型配置
  移除手动添加的typeRoots配置（TypeScript会自动扫描node_modules下所有包的类型文件），同时将types字段修改为["vite"]（Vite的类型入口为vite，vite/client会被自动包含）：

  "compilerOptions": {
    // 保留其他原有配置
    "types": ["vite"]
  }
  

• 修正tsconfig.node.json配置
  确保被引用的tsconfig.node.json符合Vite配置文件的类型检查要求，示例配置：

  {
    "compilerOptions": {
      "composite": true,
      "skipLibCheck": true,
      "module": "ESNext",
      "moduleResolution": "Node",
      "allowSyntheticDefaultImports": true
    },
    "include": ["vite.config.ts"]
  }
  

• 统一Node.js版本
  在package.json中添加engines字段，确保Vercel使用和本地一致的Node版本，避免环境差异：

  "engines": {
    "node": ">=18.0.0"
  }
  

• 清除Vercel构建缓存
  进入Vercel控制台对应项目的Deployments页面，选择最近的构建记录，点击Redeploy并勾选Clear build cache后重新构建。

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