Vite(Vue)+TypeScript构建报TS2304找不到已定义变量错误

• 开发技术栈为Vite(Vue) + TypeScript
• 执行构建命令yarn build（实际执行逻辑为vue-tsc --noEmit && vite build）时，控制台批量抛出TS2304类型错误，典型报错为：error TS2304: Cannot find name 'title'
• 经确认，报错提示找不到的变量均已在代码中明确定义
• 初步怀疑问题和<script setup lang="ts">语法的编译逻辑有关
• 当前项目tsconfig.json配置如下：

{
  "compilerOptions": {
    "target": "esnext",
    "useDefineForClassFields": true,
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": [
      "esnext",
      "dom"
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "src/*"
      ]
    },
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ],
  "references": [
    {
      "path": "./tsconfig.node.json"
    }
  ]
}

90%的这类报错都是因为缺失TS环境声明文件，导致vue-tsc无法正确解析.vue单文件组件的<script setup>语法上下文，把模板中引用的setup作用域变量误判定为未定义，按以下步骤排查修复即可：

1. 补全缺失的TS类型声明文件
   在src目录下新建env.d.ts文件，写入以下必填类型声明，这是Vite+Vue3+TS项目的标配文件，缺失就会出现各类.vue文件的TS识别异常：

/// <reference types="vite/client" />

declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, any>
  export default component
}

你现有tsconfig的include规则已经覆盖了src/**/*.d.ts，不需要额外调整配置。

2. 校验依赖版本兼容性
   如果补全声明文件后仍报错，删除本地node_modules目录和包管理器锁文件（yarn.lock/package-lock.json/pnpm-lock.yaml），重新安装依赖，同时确认几个核心包的版本符合要求：

• vue版本≥3.2.0（<script setup>语法在该版本正式稳定，低版本存在大量类型识别bug）
• vue-tsc版本和本地安装的typescript版本大版本保持对齐，同时和@vitejs/plugin-vue版本兼容

3. 排查SFC文件写法问题
   检查报错对应的.vue文件，不要在单个文件里混用带setup选项的普通<script>块和<script setup>块，多脚本块的作用域混淆也会触发vue-tsc的变量识别错误。

修复完成后重新执行yarn build，TS2304类报错就会全部消除。

内容的提问来源于stack exchange，提问作者May W.