webstorm 不会自动识别 gatsby 脚本，必须手动创建 npm 运行配置才能启用“run gatsby”功能；右键无菜单项是因为 ide 不扫描 package.json 的 script 别名，仅支持显式定义的 run configuration。
WebStorm 能直接启动 Gatsby 项目，但必须手动配置 npm 运行脚本 —— 它不会自动识别 gatsby develop 或 gatsby build，除非你显式创建一个运行配置。
为什么右键没看到 “Run Gatsby” 菜单项
WebStorm 不像对 Vite 或 Create React App 那样内置 Gatsby 支持。它不会扫描 package.json 中的任意 script 名称并自动注册为可运行项。只有当你在 Run Configuration 里明确定义了命令，它才出现在菜单或工具栏中。
- 常见错误现象：终端里
npm run develop正常，但在 WebStorm 右键项目根目录 → 没有 “Run Gatsby” 选项 - 根本原因：WebStorm 的运行配置是独立管理的，不依赖 package.json 的 script 别名自动发现
- 即使
scripts里写了"develop": "gatsby develop"，也必须手动建配置才能触发 IDE 集成（如端口监听、自动打开浏览器、热更新状态栏）
手动创建 Gatsby 开发运行配置
这是最可靠且能启用完整 IDE 功能（如调试、端口检测、自动重载）的方式：
- 点击菜单栏
Run→Edit Configurations… - 左侧面板点击
+→ 选择npm - 填写字段：
–Name: 填Gatsby develop
–Package.json script: 选develop（前提是package.json里有该 script）
–Working directory: 自动填充为项目根路径，保持默认即可
–Node interpreter: 确保指向你项目实际使用的 Node.js 版本（尤其当系统装了多个 Node 时） - 勾选
Allow parallel run（方便同时跑 Storybook 或 API 服务） - 点击
OK保存
之后你就能在顶部工具栏看到 Gatsby develop 下拉按钮，或按 Ctrl+R 快速启动。
启动后打不开 http://localhost:8000？检查这三项
WebStorm 启动成功不代表浏览器自动打开，也不代表端口一定可用 —— Gatsby 默认用 8000，但冲突很常见：
- 确认终端输出里是否出现
http://localhost:8000和http://localhost:8000/___graphql；如果只显示success Building development bundle但没地址，说明进程卡在构建阶段（常见于插件报错或gatsby-node.js语法错误） - 检查
Settings > Tools > Web Browsers and Preview中是否启用了Open browser并设为默认浏览器；否则需手动访问地址 - 若提示
EADDRINUSE，说明 8000 被占用：可在package.json的 script 中改成"develop": "gatsby develop -p 8001"，或在运行配置的Environment variables里加GATSBY_PORT=8001
GraphQL Explorer 打不开或类型无提示？不是 WebStorm 的锅
http://localhost:8000/___graphql 是 Gatsby 自带的 GraphiQL 界面，和 WebStorm 无关；但你在 .ts 文件里写 GraphQL 查询时类型缺失，往往是因为：
- 项目没装
@types/gatsby（TS 项目必需） -
tsconfig.json里没包含src/**/*.{ts,tsx}，导致类型服务没覆盖到页面文件 - WebStorm 使用了全局 TypeScript 版本而非项目本地版本：进入
Settings > Languages & Frameworks > TypeScript，把Version改为Project preferences，路径指向node_modules/typescript
改完记得点 File > Reload project from Disk，否则缓存会让类型提示延迟甚至失效。
