必须装volar（切taken over mode）和nuxt devtools插件，否则definepagemeta、useasyncdata、~/别名全标红且类型推导失效；volar默认strict mode不识别nuxt顶层api，须切换taken over mode并重启ts服务，同时tsconfig.json需配置baseurl/paths及"types": ["nuxt"]，调试须用pwa-node调用npx nuxi dev。
必须装 Volar（切 Taken Over Mode）和 Nuxt DevTools 插件，否则 definePageMeta、useAsyncData、~/ 别名全标红，类型推导失效——插件没配对，后面所有配置都是白忙。
为什么 Volar 必须切到 Taken Over Mode
Volar 默认是 Strict Mode，只处理标准 Vue 语法。Nuxt 3 的顶层 API（如 definePageMeta、useRuntimeConfig）和 script setup 中的自动导入逻辑，在 Strict Mode 下完全不识别，编辑器直接报错或无提示。
- 打开命令面板（
Ctrl+Shift+P），输入Volar: Switch to Taken Over Mode并执行 - 重启 VSCode 或至少重载窗口（
Ctrl+Shift+P→Developer: Reload Window） - 别装
Vetur：它与 Volar 冲突，会导致整个.vue文件的类型系统崩掉
tsconfig.json 或 jsconfig.json 必须手动补 baseUrl 和 paths
VSCode 不读取 nuxt.config.ts 里的 alias 配置，~/components/Hello.vue 运行时能加载，但编辑器里照样标红，因为 TypeScript 类型系统根本不知道 ~ 指向哪。
- 在项目根目录的
tsconfig.json（TS 项目）或jsconfig.json（JS 项目）中，确保compilerOptions包含：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"~/*": ["src/*"],
"@/*": ["src/*"]
}
}
}
- 改完后必须执行
Ctrl+Shift+P→TypeScript: Restart TS server，否则缓存未清，提示照旧失效 - 如果项目根目录连
tsconfig.json或jsconfig.json都没有，VSCode 默认当纯 JS 处理，definePageMeta直接不识别
调试要用 pwa-node + npx nuxi dev，不能用 node 类型
type: "node" 是错的——nuxi dev 启动的是封装后的进程，不是裸 Node.js，VSCode 默认调试器抓不到上下文，断点全灰。
-
launch.json正确写法：
{
"type": "pwa-node",
"request": "launch",
"name": "Nuxt Dev",
"runtimeExecutable": "npx",
"runtimeArgs": ["nuxi", "dev"],
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen"
}
-
runtimeExecutable必须是"npx"，不是"nuxi"：VSCode 调试模式下不读全局 PATH，写死"nuxi"会直接报command not found - 服务端断点（如
server/api/hello.ts）只在浏览器真实发起 HTTP 请求时触发；客户端断点（如pages/index.vue）要等 hydration 完成后才生效，首次加载可能跳过
Nuxt DevTools 插件不是可选项，而是语义支持的开关
它不只是右下角多一个图标，而是激活 ~/ 别名解析、useServerSeoMeta 类型识别、服务端组件高亮、运行时日志查看等能力的核心依赖。
- 不装它，VSCode 就当普通 Vue 项目处理：
pages/index.vue里写definePageMeta会标红，useRuntimeConfig没提示，server/plugins/文件里写export default defineNitroPlugin也不识别 - 启用方式：安装插件后，启动
nuxi dev --devtools（显式启用），或确保nuxt.config.ts中devtools: { enabled: true } - 如果右下角没出现 Nuxt 图标，检查是否已运行
nuxi dev，且终端输出包含DevTools enabled
最容易被忽略的是：tsconfig.json 中没加 "types": ["nuxt"]（TS 项目），会导致 useRuntimeConfig 等函数完全没类型提示；还有人以为装了插件就一劳永逸，结果忘了重启 TS Server，缓存让所有路径配置形同虚设。
