vite-env.d.ts 不认 .vue？用 TaoToken 接入的 Codex 排查声明

Cannot find module ./App.vue or its corresponding type declarations.这条报错几乎每个用 Vite 起 Vue TypeScript 项目的人都会撞上一次。它出现在import App from ./App.vue这一行红波浪线不消失命令行里vue-tsc一跑也直接失败。本文从这条报错切入先把 Codex 接到 TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content的统一模型通道拿到可用的 Key 与 Base URL再让走 TaoToken 的 Codex 对照 vite-env.d.ts、tsconfig 的 include 范围和 DefineComponent 声明逐项检查最后用vue-tsc与 Vite 启动两种方式确认./App.vue是否还报红。需要提前说清一点TaoToken 在这里只提供 Key 和 Base URL不替代 vite-env.d.ts 本身声明文件该补还是要补tsconfig 该改还是要改Codex 负责的是把检查项列全、把遗漏位置指出来。很多人误以为装了 Vue Official 插件就万事大吉编辑器确实不红了但换一台机器、换一个 CI 环境tsc依旧会报 TS2307。本篇的动作顺序是注册、建 Key、填 Base URL、让 Codex 读配置、改声明、跑验证六步走完这类.vue模块识别问题基本能定位到具体文件。一、报错现场import App from ./App.vue 为什么在 Vite 项目里飘红TypeScript 编译器能识别的模块后缀默认只有.ts、.tsx、.d.ts这几类。.vue是单文件组件格式它要被vitejs/plugin-vue或vue-tsc先转译成 JS 与类型信息TS 才可能理解。问题在于编辑器里的语言服务和命令行里的tsc是两套东西编辑器装了 Vue Official旧称 Volar之后插件会接管.vue文件的类型推断所以你在 VS Code 里看不到红。命令行执行npx tsc --noEmit或者npx vue-tsc --noEmit走的是项目自己的 tsconfig插件帮不上忙。一旦 tsconfig 的 include 没覆盖到.vue或者没有模块声明import App from ./App.vue就会命中 TS2307。典型的现象长这样import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)第一行、第二行都没问题只有./App.vue被标红鼠标悬停提示找不到模块或对应的类型声明。另一个常见变体是 Vetur 与 Vue Official 同时启用两个插件对.vue的处理方式冲突报错信息会变得更混乱。要彻底解决思路有两个方向。一是装插件让编辑器闭嘴二是让项目自身具备声明能力也就是在vite-env.d.ts或env.d.ts、shims-vue.d.ts里写模块声明。第二种才是可移植的做法CI、Docker、同事的机器都不依赖插件配置。本节的结论就是不管装没装插件声明块都建议留着。二、TaoToken 前置Key 与 Base URL 拿到手在动手改声明文件之前先把排查用的模型通道准备好。打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号进入控制台创建 API Key你会得到一串形如YOUR_API_KEY的凭证。这个 Key 就是后面 Codex 调用的身份标识。接进来之后要记两个值Base URLhttps://taotoken.net/api注意这个地址不带任何查询参数直接填这一段。API Key控制台生成的YOUR_API_KEY建议放进环境变量不要硬编码进仓库。创建 Key 的入口在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 里面可以管理多个 Key方便按项目或按机器区分。配置细节、字段含义、可用模型列表这类信息统一看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 不要凭记忆猜字段名。这里再强调一次边界TaoToken 不会读取你的 vite-env.d.ts也不会替你修改 tsconfig。它提供的是模型调用通道Codex 通过这个通道拿到推理能力然后在你的项目目录里读文件、执行命令、给出排查结论。声明文件的正确性仍然由你项目里的配置决定。三、Codex 的 config.toml 可复制配置Codex 的配置写在~/.codex/config.tomlWindows 一般是%USERPROFILE%\.codex\config.toml。下面这份配置把 provider 指向 TaoTokenKey 从环境变量读取避免明文落盘# ~/.codex/config.toml model MODEL_ID model_provider taotoken model_reasoning_effort medium [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses几个字段的填法说明model填你在 TaoToken 控制台或接入文档里确认可用的MODEL_ID不要照抄示例里的占位符。base_url固定为https://taotoken.net/api多余路径不要加。env_key指向环境变量名真正的值在 shell 里设置。wire_api的取值以接入文档为准若文档说明走 chat 兼容接口就按文档调整。设置环境变量# macOS / Linux export TAOTOKEN_API_KEYYOUR_API_KEY # Windows PowerShell $env:TAOTOKEN_API_KEYYOUR_API_KEY设置完成后在项目根目录执行codex进入交互或者用codex exec ...跑一次性的只读检查任务。第一次跑建议问一个与项目无关的小问题确认通道是通的再让它读项目文件。四、让 Codex 对照 vite-env.d.ts 排查声明含可复制声明块通道打通后把 Codex 的工作目录切到 Vite 项目根目录让它按下面的顺序做只读排查。这份提示词可以直接复制把检查项一次交代清楚这是一个 Vite Vue TypeScript 项目报错是 TS2307import App from ./App.vue 找不到模块。 请只做只读检查不要修改文件按顺序输出 1. 列出项目里所有 .d.ts 文件路径找出 vite-env.d.ts、env.d.ts、shims-vue.d.ts 是否存在 2. 读取 tsconfig.json如果它引用了 tsconfig.app.json 或 tsconfig.node.json也要一并读取 3. 检查 include 数组是否覆盖 src 下的 .ts、.d.ts、.tsx、.vue以及 vite-env.d.ts 所在路径 4. 检查是否已有 declare module *.vue 声明块重复声明是否冲突 5. 检查 compilerOptions.types确认 vite/client 类型有没有被白名单排除 6. 输出一份需要修改的文件清单和每处修改原因。Codex 可能会指出声明块缺失或写法不完整。标准写法如下放在src/vite-env.d.ts或项目根的env.d.ts中/// reference typesvite/client / declare module *.vue { import type { DefineComponent } from vue const component: DefineComponent{}, {}, any export default component }这里三件事要理解到位不要只抄代码第一行/// reference typesvite/client /是让 TS 加载 Vite 的客户端类型import.meta.env、静态资源导入这些能力都靠它。缺这一行即使.vue声明写对了import.meta.env.BASE_URL之类的地方还是会报错。declare module *.vue是通配模块声明告诉 TS任何以.vue结尾的导入都按下面的形状处理。少了它TS 只能靠插件猜。DefineComponent是 Vue 暴露的组件类型用它来标注默认导出能得到基本的组件类型约束。{}, {}, any三个泛型分别对应 props、暴露的绑定和数据类型属于让 TS 先接受的宽松写法项目对 props 类型要求严格时再配合vue-tsc和组件内部的defineComponent做更精确的推导。接下来是 include 范围。很多“声明写了还是报红”的案例问题就出在这里。假设vite-env.d.ts放在项目根目录而 tsconfig 的 include 只写了src那么根目录的声明文件根本不在编译单元里写了等于没写。参考配置{ include: [ src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue, src/vite-env.d.ts ] }如果声明文件放在根目录就把最后一行换成vite-env.d.ts如果项目用了tsconfig.app.json要注意真正生效的是被引用的子配置改完根文件还要确认子文件里没有被覆盖。让 Codex 把这些文件一起读出来对比比手动翻更省事。五、验证vue-tsc 与 Vite 启动的成功结果改完声明和 include 之后必须用命令验证不能只看编辑器颜色。让 Codex 执行以下两条npx vue-tsc --noEmit npx vite build或者直接起开发服务器npm run dev判断成功的标准vue-tsc --noEmit退出码为 0终端没有 TS2307 相关输出。vite build完成构建./App.vue不再出现在错误列表里。开发服务器正常启动浏览器控制台没有模块解析失败的错误。回到编辑器之前飘红的import App from ./App.vue恢复为正常颜色悬停能看到组件类型提示。如果vue-tsc报错行数和之前一致说明声明文件没被加载回到 include 检查。如果vue-tsc通过但编辑器仍红多数是 TS Server 缓存问题执行“TypeScript: Restart TS Server”再观察。把这两类结果分开看能避免把配置问题和缓存问题混在一起排查。六、vite-env.d.ts 写了仍报红的常见错排查下面这些情况在本篇场景里出现频率很高按顺序排一遍基本能命中声明文件位置在根目录tsconfig 的 include 只覆盖了 src文件没进入编译范围。把路径加进 include或把声明文件移到 src 下。项目采用tsconfig.json引用tsconfig.app.json的分层结构你改的是根文件实际生效的是子文件。两处都要确认。同时存在shims-vue.d.ts和vite-env.d.ts两个文件都写了declare module *.vue其中一个写法不完整或缺少export default导致声明合并后类型异常。保留一处即可。compilerOptions.types配置了白名单只写了[node]之类把vite/client挡在外面。补上vite/client或者删掉该字段让 TS 自动加载。VS Code 里 Vetur 与 Vue Official 同时启用.vue的语言服务被两个插件争抢。禁用 Vetur只留 Vue Official。tsc与vue-tsc混用。纯tsc不认识.vue语法检查.vue文件请用vue-tsc。Codex 请求侧的问题base_url写成了带/v1的地址或环境变量名与env_key不一致导致模型请求失败看起来像是“排查没结果”。核对https://taotoken.net/api和TAOTOKEN_API_KEY两处即可。排查时建议一次只改一个变量每改一次就跑一遍vue-tsc --noEmit这样报错行数的变化能直接反映改动是否有效。七、把 Codex 固定到 TaoToken 通道声明类排障就有统一入口Vite Vue 的模块声明问题本质是三个东西的配合.d.ts里的模块声明、tsconfig 的 include 范围、以及执行校验的命令行工具。把 Codex 接到 TaoToken 的通道之后这套检查可以固定下来Key 从 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 创建字段含义对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc Base URL 固定https://taotoken.net/api每次遇到import App from ./App.vue飘红就让 Codex 按第四节的提示词读一遍文件清单再跑vue-tsc --noEmit验证。如果这类前端工程排查是长期、高频的工作可以把通道升级为 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 把 Codex 作为固定的工程检查入口声明文件、tsconfig、构建命令三者的改动都能在一次会话里核对完。