必须装volar（切taken over mode）和nuxt devtools，配好tsconfig.json/jsconfig.json别名与types，并用pwa-node调试npx nuxi dev；缺一即导致definepagemeta标红、~/components跳转失败、服务端断点不触发。
必须装 Volar（切到 Taken Over Mode）和 Nuxt DevTools 插件，配好 tsconfig.json 或 jsconfig.json 的别名与类型声明，并用 pwa-node 类型调用 npx nuxi dev 启动调试——三者缺一不可，否则 definePageMeta 标红、~/components 跳转失败、服务端断点不触发。
Volar 必须切到 Taken Over Mode
Nuxt 3 的顶层 API（如 definePageMeta、useAsyncData、useRuntimeConfig）在 Volar 默认的 Strict Mode 下完全不识别，编辑器会直接报错或无提示，这不是代码问题，是模式没对。
- 按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入并执行Volar: Switch to Taken Over Mode - 切换后必须**关闭整个 VSCode 窗口**，再重新打开项目文件夹——仅重载窗口不够，TS Server 不会真正重载
- 彻底禁用
Vetur：它和 Volar 冲突，会导致所有.vue文件的类型系统崩掉
tsconfig.json 或 jsconfig.json 必须显式配置别名与类型
VSCode 不读取 nuxt.config.ts 中的 alias，也不自动继承 .nuxt/tsconfig.json，~/ 和 @/ 在编辑器里标红，是因为 TypeScript 类型系统根本不知道它们指向哪。
- TS 项目：确保根目录有
tsconfig.json，至少包含：{ "extends": "./.nuxt/tsconfig.json", "compilerOptions": { "types": ["nuxt"] } } - JS 项目：用
jsconfig.json，内容至少为：{ "compilerOptions": { "baseUrl": ".", "paths": { "~/*": ["src/*"], "@/*": ["src/*"] } } } - 改完后立刻执行
Ctrl+Shift+P→TypeScript: Restart TS server，否则缓存未清，提示照旧失效
launch.json 必须用 pwa-node + npx nuxi dev
"type": "node" 是错的。Nuxt 3 启动的是封装后的 nuxi dev 进程，不是裸 Node.js，VSCode 默认调试器抓不到上下文，断点全灰。
- 在
.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 完成后才生效，首次加载可能跳过
最容易被忽略的是：Volar 切换模式后不关窗重开、TS Server 不重启、runtimeExecutable 写成 nuxi——这三个动作任意一个漏掉，调试链就断了，所有“标红”“跳转失败”“断点不触发”都是表象，根源都在这里。
