Vue 3 + TypeScript 引用模板变量时提示Cannot find name如何解决

核心排查步骤 #

• 校验单文件组件语法格式：使用TypeScript的Vue文件必须在<script>标签上添加lang="ts"声明；使用组合式API的场景需额外确认是否添加了setup属性，正确示例为<script setup lang="ts">。
• 确认变量已暴露到模板上下文：
  • 选项式API场景：变量必须声明在data、computed、methods等官方配置项内，仅在<script>顶层声明未挂载到实例的变量无法被模板识别。
  • 组合式API场景：<script setup>块内的顶层变量、导入的模块/组件默认直接暴露给模板；如果未使用setup属性，需要在setup()函数中手动return对应变量，模板才能正常访问。
• 检查TypeScript相关配置：
  • 确认项目已安装vue-tsc、@vitejs/plugin-vue（Vite项目）或vue-loader（Webpack项目）的稳定版本，旧版本依赖可能存在模板类型识别缺陷。
  • 核对根目录tsconfig.json的配置，确保包含以下必要规则：

  {
    "compilerOptions": {
      "types": ["vue/ref-macros"]
    },
    "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
  }
  

• 排查命名冲突：确认模板引用的变量名未和全局变量、注册的组件名、导入的第三方模块名重名，避免作用域覆盖导致类型识别失败。
• 校验编译器宏使用规范：defineProps、defineEmits、defineExpose等Vue内置宏无需手动导入，手动导入会触发类型识别异常。

快速修复方案 #

• 编辑器本地校验报错的场景，直接重启TypeScript服务即可：VS Code下按Ctrl+Shift+P（Mac系统为Cmd+Shift+P），搜索「Restart TS Server」执行后等待服务重启完成。
• 编译阶段报错的场景，先删除node_modules、.vite、dist等缓存目录，重新执行依赖安装命令后再启动项目。
• 临时调试可在报错的模板行上方添加<!-- @vue-ignore -->注释跳过当前行的类型校验，不建议长期保留该注释。

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