根本原因是WebStorm未识别合法启动脚本：仅认package.json中大小写敏感的"storybook"脚本，且命令须以start-storybook或build-storybook开头；别名跳转失败因tsconfig.json未配baseUrl/paths；类型报红因未用项目本地TS或误装@types/storybook__react；HMR失效多因Safe write未关闭。
WebStorm 为什么找不到 “Run Storybook” 菜单项
根本原因不是 WebStorm 不支持，而是它没识别到合法的启动脚本。WebStorm 只认 package.json 中名为 storybook 的 script（大小写敏感），且命令必须以 start-storybook 或 build-storybook 开头。
常见错误现象：右键项目根目录或 .storybook 文件夹，菜单里没有 “Run Storybook”；终端能跑通，但 IDE 无响应。
- 确保
scripts块中存在："storybook": "start-storybook -p 6006 -s ./public"（-s可选，用于静态资源） - 别用
sb:dev、dev:storybook这类自定义名——WebStorm 不会自动发现，只能手动建 npm 运行配置 - 若用 pnpm，WebStorm 版本需 ≥ 2023.3；否则在 Settings > Tools > Terminal 中把 shell path 指向
pnpm可执行文件
组件路径别名（如 @/components）跳转失败
Ctrl+Click 点击 import Button from '@/components/Button' 却跳转到 404 或拼错路径？这不是 WebStorm 故障，是 TypeScript 语言服务没读到路径映射。
WebStorm 的跳转、补全、类型检查全部依赖 tsconfig.json（或 jsconfig.json）中的 baseUrl 和 paths 配置，webpack 的 resolve.alias 对它完全无效。
- 在
tsconfig.json中补全："baseUrl": "./", "paths": { "@/*": ["src/*"] } - 改完后必须执行 File > Reload project from Disk，否则缓存不更新，映射仍不生效
- 如果项目是 JS 项目，用
jsconfig.json同样结构，WebStorm 同样识别
.stories.tsx 文件里 args、Meta 类型报红或无补全
症状包括：args 参数无类型提示、Meta 类型标红、export default { component: Button } as Meta 提示 “Type ‘{ component: typeof Button; }’ is not assignable to type ‘Meta’”。
本质是类型包未加载，或与当前 TS 版本不兼容。
- Storybook v7+ 已将类型内置在
@storybook/react（或其他框架包）中，不要装@types/storybook__react，装了反而冲突 - 进 Settings > Languages & Frameworks > TypeScript，勾选
Use TypeScript version in node_modules，确保 WebStorm 用的是项目本地 TS -
.storybook/main.ts必须用 ES Module 导出：export default defineConfig({ ... })；若误写为module.exports = { ... }，WebStorm 的 JS/TS 混合解析会失效，类型直接丢失
修改组件后 Storybook 不热更新（HMR 失效）
保存文件后浏览器没反应，控制台也没 HMR 日志？大概率是 WebStorm 的 “Safe write” 干扰了 webpack-dev-server 的文件监听机制。
webpack/vite 的 HMR 依赖底层 fs.watch，而 WebStorm 默认开启 Safe write（先写临时文件再原子替换），导致监听器错过变更事件。
- 关闭 Safe write：Settings > Appearance & Behavior > System Settings → 取消勾选
Use “safe write” (save changes to a temporary file first) - 同时建议关闭
Synchronize files on frame activation，避免切回 IDE 时触发多余同步 - 重启 WebStorm 或至少执行 File > Reload project from Disk，让新设置生效
真正卡住的地方往往不在 Storybook 配置本身，而在 WebStorm 是否“信任”你的项目结构——路径映射没 reload、TS 版本没切对、Safe write 没关掉，三者任一缺失，都会让跳转、类型、HMR 全线失灵。
