结论：Nuxt 3 的 server/routes/ TS 文件需在 tsconfig.json 中显式 include "server/routes/**/*"，并启用 Volar TS 插件（"volar.typescriptPlugin.enable": true），否则 defineEventHandler 等全局 API 无类型提示、无法跳转、补全失效。
直接说结论：Nuxt 3 的服务端路由（server/routes/）开发，配合 VSCode 快捷键的核心提效点不在“写得更快”，而在“改得更准、查得更稳、验得更早”——尤其当你要在 server/routes/hello.ts 里写一个返回 JSON 的 API，又想立刻在 pages/index.vue 中用 useFetch 调它，还顺手加个类型定义时，快捷键和配置缺一不可。
如何让 VSCode 正确识别 server/routes 下的 TS 文件并提供补全
Nuxt 3 默认不把 server/routes/ 视为 TypeScript 模块根目录，所以你在 server/routes/test.ts 里写 defineEventHandler，VSCode 可能报“无法找到名称 ‘defineEventHandler’”，哪怕它实际能跑通。
- 必须在项目根目录的
tsconfig.json中确保"include"包含"server/routes/**/*"，否则 Volar 和 TS 插件不会扫描这些文件 - 在
.vscode/settings.json中启用 Volar 的 TS 支持："volar.typescriptPlugin.enable": true，否则defineEventHandler的参数类型（如event.context）不会被推导 - 不要依赖
import { defineEventHandler } from 'h3'—— Nuxt 3 已全局注入，手动 import 反而可能触发类型冲突；但若你写了，VSCode 必须能跳转到正确的h3类型声明，这依赖node_modules/.pnpm/h3@...路径被正确索引
Ctrl+Alt+G 绑定 codegeex.generate 后，在 server/routes 里怎么用才不踩坑
你在 server/routes/user/[id].ts 里光标停在函数体开头，按 Ctrl+Alt+G，想让它生成一个带 getValidatedBody 校验的 POST 处理器——但默认 prompt 很容易忽略 Nuxt 的上下文约束。
- 先按
Ctrl+Alt+F注入当前文件上下文，确保 CodeGeex 知道这是 H3 风格的事件处理器，不是 Express 或 Fastify - 输入 prompt 时明确带上约束词，例如：“用 Nuxt 3 server routes 写一个 POST 接口，校验 body 中的 email 字段为必填且格式合法，返回 400 或 201”
- 生成后务必检查是否用了
event.context.nuxt（不该出现）、是否误用了req.body（H3 用readBody(event)），这类错误 VSCode 不会自动标红，但运行时报错
调试 server/routes 时，为什么 launch.json 的 configuration 不能只配 "program"
你照搬 Node.js 项目配置，在 .vscode/launch.json 里写 "program": "./server/routes/hello.ts"，启动就报错：Error: Cannot find module 'h3'。
- Nuxt 的 server routes 不是独立可执行的 TS 文件，它们由 Nitro 构建后统一托管，不能直接用 ts-node 运行
- 正确做法是调试整个 Nitro 服务：配置
"type": "node"+"request": "launch"+"program": "./.nuxt/dist/server/index.mjs"（构建后路径），再配合"preLaunchTask": "build" - 更实用的是用
console.log+Ctrl+Shift+P → "Developer: Toggle Developer Tools"查看终端输出，比断点更轻量；Nitro 日志默认输出请求路径和状态码，足够定位 500 错误源头
pages/ 和 server/routes/ 之间跳转时，为什么 Ctrl+Click 有时失效
你在 pages/index.vue 里写了 await $fetch('/api/hello')，想 Ctrl+Click 跳转到 server/routes/api/hello.ts，结果跳到了 node_modules/nuxt/dist/app/composables/fetch.mjs。
- VSCode 默认不解析 Nuxt 的路由映射规则，
/api/hello是运行时路径，不是文件路径，Ctrl+Click 无法反向映射 - 解决方案是：在
server/routes/api/hello.ts文件顶部加 JSDoc 注释/** @fileRoute /api/hello */，然后安装插件 “File Router for Nuxt”，它能让 Ctrl+Click 识别该注释并跳转 - 更稳妥的做法是手动维护命名约定：URL 路径
/api/hello对应文件路径server/routes/api/hello.ts，并在团队文档中固化，避免依赖编辑器自动推断
最常被忽略的一点：Nuxt 3 的 server routes 是纯服务端逻辑，它们的类型定义（如 defineEventHandler 返回值）只在构建时生效，VSCode 的实时类型检查依赖 tsconfig 的 include 和 volar 插件协同，少任何一个环节，补全就断——这不是快捷键能解决的，而是配置链的完整性问题。
