Next.js 13+ 默认启用 --turbopack 导致 WebStorm 启动卡在“Starting the development server…”，应删掉 package.json 中 dev 脚本的 --turbopack，改用传统模式，并正确配置 NPM Run Configuration、框架支持及环境。
WebStorm 启动 Next.js 卡在 “Starting the development server…”
这不是 WebStorm 崩了，而是 Next.js 13+ 默认启用 --turbopack 导致的兼容断层——WebStorm 的 Run Configuration 目前无法注入调试上下文到 Turbopack 进程里。
- 打开
package.json，把"dev": "next dev --turbopack"改成"dev": "next dev"（直接删掉--turbopack） - 在 WebStorm 中新建 Run Configuration：类型选
NPM→Command填run→Scripts选dev→ 勾选Run npm install automatically before running - 别直接点绿色三角！先点右上角配置下拉箭头，确认当前激活的是你刚建的 NPM 配置；否则 WebStorm 可能 fallback 到 shell 执行，丢失 Node 环境变量
- 如果仍卡住，切到终端手动运行
npx next dev，真实报错通常只有两种：EADDRINUSE（端口被占）或permission denied（node_modules权限异常，尤其 macOS / WSL）
WebStorm 识别不了 pages 或 app 目录、跳转/自动导入失效
根本原因不是插件没装，而是 WebStorm 没被明确告知“这是 Next.js 项目”——它默认当普通 Node.js 项目解析，不激活路由映射和框架语义。
- 确认
package.json里有"next"（在dependencies或devDependencies中都行） - 右键项目根目录 →
Add Framework Support…→ 勾选Next.js→ 点 OK - 若没这个选项，进
Settings → Plugins搜Next.js Support，确保已启用；版本太老（ - 重启 WebStorm 后，
pages或app目录会自动标为源码根目录，Link跳转、import自动补全才真正生效
TS 类型全红、GetServerSideProps 报错、路径别名不识别
Next.js 的类型系统不靠 node_modules/next 自动注入，必须靠 tsconfig.json 显式声明继承和映射，WebStorm 不会猜你用的是 App Router 还是 Pages Router。
- 确保根目录有
tsconfig.json，且含"extends": "next/env"（Next.js 13.4+ 推荐），或至少有"types": ["next"] - 若用了
paths别名（如@/components），必须配"baseUrl": "."和完整"paths"，否则跳转、自动导入全部失灵 -
getServerSideProps等函数需显式 import 类型：import { GetServerSideProps } from 'next'，不能只靠全局声明 - 改完
tsconfig.json后，点 WebStorm 右上角TypeScript Language Service → Restart TypeScript Service，否则缓存不刷新，类型还是红的
断点进不去 getServerSideProps 或服务端 fetch
浏览器 DevTools 或 JavaScript Debug 配置完全无效——SSR 逻辑只在 Node 进程中执行，WebStorm 必须连上真正的服务端进程才能命中断点。
- 启动命令必须加
--inspect：Mac/Linux 用npx next dev --inspect=0.0.0.0:9229，Windows 用npx next dev --inspect=127.0.0.1:9229 - 在 WebStorm 中新建
Node.js类型的 Run Configuration，JavaScript file留空，Application parameters填dev --inspect=0.0.0.0:9229，Node parameters填--inspect-brk（可选） - 确保
node_modules/.bin/next可执行；若报command not found，改用npx next dev --inspect=... - 断点只能打在
getServerSideProps函数体内部、服务端fetch调用处，客户端组件里打的断点对 SSR 逻辑无意义
最常被忽略的一点：WebStorm 对 Next.js 的支持不是“开箱即用”，而是“声明即启用”——你得主动告诉它这是 Next.js 项目，而不是等它自动识别。任何一步漏掉（比如没点 Add Framework Support、没改 tsconfig.json、没加 --inspect），断点、跳转、类型都会局部或整体失效。
