★ FEATURED ARTICLE 1. 刚建好的 vue3vitets 项目为什么满屏红波浪线你大概率刚敲完npm create vitelatest my-app -- --template vue-tsnpm install也跑完了npm run dev浏览器里页面正常渲染结果切回 VSCode 一看main.ts里import App from ./App.vue下面一条红波浪线.vue文件里defineProps、模板里的变量也到处飘红。终端能跑、编辑器报错这种割裂感最让人抓狂。先说清楚这件事的本质VSCode 的红波浪线不等于代码真的错了。它来自编辑器里 TypeScript 语言服务tsserver的静态分析结果而vite dev走的是 esbuild 转译两者对「什么算合法代码」的判断标准不一样。esbuild 只做转译不做类型检查.vue文件它压根不关心类型但 tsserver 默认只认.ts/.tsx/.js遇到.vue后缀就懵了于是报Cannot find module ./App.vue or its corresponding type declarations。所以排查方向不是去改业务代码而是回答三个问题谁在给 VSCode 提供类型信息它认不认.vue它的配置和项目实际结构对不对得上这三个问题分别对应 Volar现名 Vue - Official、tsconfig.json、以及env.d.ts类型声明文件。这篇面向的是刚接触 vue3 vite ts 组合、被编辑器报错卡住的开发者。我会把波浪线的几类根因拆开讲给出可以直接复制的settings.json和tsconfig.json骨架最后演示怎么用 TaoToken 的统一 Key 把 AI 辅助诊断接进来——当你面对一堆报错不知道从哪条读起时让模型帮你按优先级梳理比一条条搜快得多。全程不需要你懂 tsserver 内部原理跟着配就行。2. 动手前先把 TaoToken 的 Key 和通道准备好排查配置这件事本身不难难的是报错信息五花八门同一个波浪线可能是 Volar 没生效也可能是tsconfig的include没覆盖到还可能是 ESLint 和 TS 插件打架。我自己的做法是把项目结构和报错原文丢给 AI让它先给一个排查顺序再逐条验证。这样比盲目试错省时间。要让 AI 工具稳定可用得先有个统一的调用入口。TaoToken 在这里的作用是提供统一的 API Key 和兼容接口你申请一次之后不管是接 Claude Code、Cursor 这类编码工具还是自己写脚本调模型对话都用同一个 Key不用每个工具单独配一套凭证。对排查场景来说好处是你可以在编辑器里直接问「这个 tsconfig 报错什么意思」不用切来切去。准备步骤很直接。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建 API Key。Key 只在创建时完整显示一次复制下来存到安全的地方别提交进 Git。拿到 Key 之后接口地址用 https://taotoken.net/api这个不加 UTM 参数直接作为 base URL。如果你用的是支持自定义 base URL 的编码工具把这两项填进去就能跑。想先验证 Key 是否可用可以去模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息试试能正常返回就说明通道没问题。注意API Key 属于敏感凭证建议放在环境变量或工具的密钥管理里不要硬编码进settings.json或提交到仓库。团队协作时每人用自己的 Key。如果你打算长期用 AI 辅助编码、跑 Agent 类任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。只是偶尔排查配置的话按量用 API 就够了。Key 的具体创建入口在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节可以对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 三类波浪线根因与可复制的配置骨架波浪线看着都一样根因分三类。先定位属于哪类再改对应文件别一股脑全改。3.1 类型声明缺失.vue模块找不到最典型的一条报错长这样Cannot find module ./App.vue or its corresponding type declarations. ts(2307)原因是 tsserver 不认识.vue后缀。Vite 官方模板会在src/下生成一个env.d.ts老版本在根目录叫vite-env.d.ts里面默认只有一行/// reference typesvite/client /。你需要补上.vue模块声明// src/env.d.ts /// reference typesvite/client / declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }这里有个容易踩的坑import type { DefineComponent } from vue必须用import type否则在某些isolatedModules配置下会报「无法在环境声明中使用值导入」。改完保存main.ts里那条 2307 应该立刻消失。如果没消失检查tsconfig.json的include有没有把src/**/*.d.ts包含进去。3.2 插件冲突Vetur 和 Volar 不能共存如果你之前装过 Vue2 项目VSCode 里可能还留着 Vetur 插件。Vetur 是为 Vue2 选项式 API 设计的对script setup和 vue3 的类型推导支持很差它和 Volar 同时启用会互相抢.vue文件的语言服务表现就是模板里变量全红、defineProps报未定义。处理方式在扩展面板搜Vetur卸载或禁用搜Vue - OfficialVolar 的现用名旧版叫Volar安装并确保启用。装完重启 VSCode 窗口CtrlShiftP→Developer: Reload Window。这一步能解决大部分「模板里飘红但代码没错」的情况。3.3 tsconfig 配置路径别名和 include 范围用/别名导入时如果报Cannot find module /xxx是tsconfig没配paths。Vite 的resolve.alias只管打包编辑器类型解析得靠tsconfig。一份能用的骨架{ compilerOptions: { target: ES2020, useDefineForClassFields: true, module: ESNext, lib: [ES2020, DOM, DOM.Iterable], skipLibCheck: true, moduleResolution: bundler, allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true, noEmit: true, jsx: preserve, strict: true, noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true, baseUrl: ., paths: { /*: [src/*] } }, include: [src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue], references: [{ path: ./tsconfig.node.json }] }关键点include必须显式包含src/**/*.vue否则.vue文件不参与类型检查Volar 拿不到上下文moduleResolution用bundler是 Vite 项目的推荐值用node会导致部分包的类型解析失败。3.4 VSCode settings.json让 Volar 接管工作区根目录建.vscode/settings.json内容如下{ typescript.tsdk: node_modules/typescript/lib, vue.server.hybridMode: true, editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.eslint: explicit }, typescript.enablePromptUseWorkspaceTsdk: true, files.eol: \n }typescript.tsdk指向项目本地的 TypeScript避免 VSCode 用内置的旧版本导致类型行为不一致vue.server.hybridMode让 Volar 用混合模式处理.vue对大型项目更稳。改完同样重启窗口。4. 验证配置是否真的生效配置改完不能只看波浪线消没消得跑一遍类型检查确认。在package.json的 scripts 里加一条{ scripts: { type-check: vue-tsc --noEmit } }然后执行npm run type-checkvue-tsc是带.vue支持的 tsc 封装它和 VSCode 里的 tsserver 用的是同一套类型逻辑。如果这条命令零报错说明类型层面是干净的编辑器里再有波浪线就是插件或缓存问题不是代码问题。实测下来改完配置后如果波浪线还在按这个顺序清一遍CtrlShiftP→TypeScript: Restart TS Server再不行就Developer: Reload Window最后删掉node_modules/.vite缓存重启 dev server。三步走完基本都能消。想确认 Volar 是否真的接管了.vue文件打开任意.vue看 VSCode 右下角语言模式是不是Vue鼠标悬停defineProps能不能弹出类型提示。能弹就说明语言服务正常。如果你在排查时对某条报错拿不准可以把报错原文和对应的tsconfig片段贴到模型对话 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里让它解释这条报错的触发条件。比搜索引擎快而且能结合你贴的上下文给具体建议。5. 本篇常见报错排查清单把高频问题集中列一下对照着查。报错信息根因处理Cannot find module ./App.vuets(2307)缺.vue模块声明补env.d.ts的declare module *.vue模板变量全红defineProps未定义Vetur 与 Volar 冲突卸载 Vetur装 Vue - OfficialCannot find module /xxxtsconfig 缺 paths配baseUrlpaths.vue文件不参与检查include 未覆盖include 加src/**/*.vue类型提示和实际不符VSCode 用了内置 TS设typescript.tsdk指向本地改完配置波浪线不消tsserver 缓存Restart TS Server Reload Window几个补充判断如果只有某个第三方库报类型错先看skipLibCheck是否为true开了能跳过node_modules里的类型检查如果是 ESLint 报的红线而非 TS 报错看.eslintrc的 parser 是不是vue-eslint-parserparserOptions 里有没有指定parser: typescript-eslint/parser。ESLint 和 TS 的报错来源不同别混着改。还有一点noUnusedLocals和noUnusedParameters开着的时候声明了没用的变量会报错这是严格模式的正常行为不是配置坏了。不想要就关掉但建议留着能帮你清理死代码。6. 把 AI 诊断接进日常流程配置类问题有个特点报错信息本身往往不直观但一旦知道根因就很简单。与其每次遇到波浪线都从头搜不如把 AI 当成第一道排查入口。用 TaoToken 统一 Key 的好处是你可以在编码工具、对话页面、脚本之间共用一套凭证不用为每个工具单独折腾配置。具体怎么接在支持自定义 API 的工具里填 base URLhttps://taotoken.net/api和你的 Key用 Claude Code 的话参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里的接入说明它对应的入口在 ClaudeCodeAnthropic https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期高频用就上 Coding Plan偶尔用按量即可。回到波浪线本身记住判断顺序先看报错码2307 是模块解析2339 是属性不存在6133 是声明未使用再看是 TS 报的还是 ESLint 报的最后确认 Volar 是否接管。这三步能覆盖九成以上的场景。剩下的边角情况把报错原文和项目结构丢给模型让它帮你缩小范围比一条条试快得多。配置这东西配一次对了后面新建项目直接复制骨架就行。
阅读完成 · 觉得有帮助？
