webstorm需手动配置node路径、tsconfig.json添加"nuxt"类型及nuxt.config.ts首行三斜线注释，才能正确识别nuxt命令、类型和调试上下文。
WebStorm 无法直接识别 nuxt 命令、definePageMeta 报红、useAsyncData 断点不触发——这些问题不是项目写错了，而是 WebStorm 没正确加载 Nuxt 的类型系统和运行上下文。核心解法就三条：手动指定 Node 路径、补全 tsconfig.json 类型声明、用对调试入口文件。
Node.js 解释器路径必须手动指定，不能选 “Project default”
WebStorm 启动时不会自动读取 shell（如 zsh / fish / nvm）的环境变量，nuxt 命令在终端能跑，IDE 里却报 command not found: nuxt 是最典型表现。
- 打开 Preferences → Languages & Frameworks → Node.js and NPM
- 把
Node interpreter改成你项目实际使用的路径，例如：/Users/xxx/.nvm/versions/node/v20.12.0/bin/node或C:\Program Files\nodejs\node.exe - 取消勾选 Manage Node.js core libraries automatically——它会强行注入旧版 @nuxt/core 类型，和你装的
nuxt@3.12.4冲突 - 改完后重启 WebStorm，再右键
nuxt.config.ts→ Reload project
defineNuxtConfig 和 definePageMeta 报红？补两行配置就行
WebStorm 不像 VS Code 那样自动推导 Nuxt 的全局类型，Cannot find name 'defineNuxtConfig' 这类错误本质是 TypeScript 服务没接上 Nuxt 的类型入口。
- 确认项目根目录有
tsconfig.json，且compilerOptions.types包含"nuxt"（不是"@nuxt/schema"，也不是空数组） - 在
nuxt.config.ts文件**最顶部第一行**加：/// <reference types="nuxt"></reference>（前面不能有任何空行或注释） - 在任意
.vue文件中使用definePageMeta时，必须写在顶层<script setup></script>内，写在setup()函数里或<script></script>外部都会语法报错
调试 useAsyncData 或服务端钩子，别右键单文件 Run/Debug
WebStorm 默认以普通 Node.js 脚本方式执行单个 .ts 或 .vue 文件，但 useAsyncData 只在完整 Nuxt 生命周期（nuxt dev 启动后）中才初始化，单独跑根本不会触发。
- 不要右键
pages/index.vue→ Debug - 改用 Run → Edit Configurations → + → Node.js
-
Working directory设为项目根目录 -
Javascript file填：node_modules/nuxt/bin/nuxt.mjs（注意是.mjs，不是.cjs） -
Application parameters填：dev
新建项目必须用 npx nuxi@latest init，别碰 create-nuxt-app
create-nuxt-app 已被官方弃用，用它建的项目大概率出现路由不生成、app.vue 结构错位、热更新失效等问题，且无法通过简单升级修复。
- 终端执行：
npx nuxi@latest init my-nuxt-app（不加-y，交互式选择更稳妥） - 初始化完成后，在 WebStorm 中用 File → Open… 打开项目**根目录**，不要用 File → New Project → Empty Project 再手动导入
- 首次打开提示 “Enable TypeScript language service” 时，务必点 Enable——否则
useAsyncData返回值类型、$fetch提示全失效
最易被忽略的是 tsconfig.json 中 "types": ["nuxt"] 和 nuxt.config.ts 顶头那行 /// <reference types="nuxt"></reference> 必须同时存在，缺一不可；很多人只改了其中一个，结果类型还是断的。
