VSCode本身不运行Storybook，所有预览失败问题90%源于服务未启动；必须先执行npm run storybook确认终端输出Local: http://localhost:6006/，再排查端口占用、main.js配置、文件命名与导出一致性。
VSCode 本身不运行 Storybook，所有“预览失败”“跳转 404”“热更新不动”的问题，90% 都是因为 npm run storybook 根本没成功跑起来——先确认服务在终端里真起来了，再谈配置。
为什么点「Open Preview」还是 ERR_CONNECTION_REFUSED
这不是插件坏了，是本地 Storybook 进程压根没启动或启动失败。
- 必须在项目根目录执行
npm run storybook（或yarn storybook），且终端输出中明确出现Local: http://localhost:6006/—— 没这行，后面全白搭 - 如果卡在
Building preview超过 90 秒，大概率是依赖解析失败或 TypeScript 类型检查阻塞，可加--no-manager-cache重试 -
ERR_CONNECTION_REFUSED时立刻查端口：macOS/Linux 运行lsof -i :6006，Windows 运行netstat -ano | findstr :6006，杀掉占用进程 - 端口可改，但必须同步改两处：
.storybook/main.js中的port: 6007，以及.vscode/settings.json中的"storybook.previewUrl": "http://localhost:6007"
右键没有「Open Story for Current File」选项
插件不是“装了就生效”，它靠 .storybook/main.js 里的 stories 字段扫描文件路径，路径错、后缀错、导出名错，菜单直接消失。
-
stories必须是数组格式，例如：stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)']—— 注意**/和括号语法，漏一个字符就扫不到 - 文件名必须严格匹配：
Button.stories.tsx✅，Button.story.tsx❌，button.stories.tsx❌（大小写敏感） - 默认导出名必须和组件名一致：
Button.stories.tsx里要export default Button或export const Button = { ... }，否则插件无法关联到Button.tsx - monorepo 场景下，插件只认当前工作区根目录的
.storybook/，子包里的配置无效；需在每个含 Storybook 的包内单独配
修改代码后 Storybook 不热更新
不是 VSCode 的锅，是 Storybook 的 HMR（热模块替换）被关了或监听范围错了，尤其 Vite 用户容易踩坑。
- Vite 构建（Storybook v7+ 默认）需确认
.storybook/main.js启用了watchOptions，且没被覆盖 - 检查项目根目录的
vite.config.ts：若存在server.hmr.overlay = false或server.watch.ignored: [/node_modules/, /dist/]里误加了/src/，HMR 就会静默失效 - 终端若出现
HMR disconnected或Failed to load module，优先看这行错误前后的 timestamp 和上下文，不是刷新页面能解决的 - 禁止在
*.stories.tsx里调用未导出的工具函数、用require()动态导入、或写副作用逻辑（如useEffect(() => { fetch(...) })），这些都会断连 HMR
想在 VSCode 侧边栏直接预览组件，不是打开浏览器
VSCode 原生不渲染网页，所谓“内嵌预览”只是用 Webview 加载你已启动的 http://localhost:6006 页面，所以一切依赖服务可用 + URL 正确。
- 装好官方插件
Storybook for VS Code后，在命令面板（Cmd+Shift+P/Ctrl+Shift+P）输入Storybook: Open Preview或Storybook: Open Preview to the Side - 必须提前在
.vscode/settings.json中写死预览地址："storybook.previewUrl": "http://localhost:6006"，否则 Webview 加载空白 - 预览页跳转到 404？不是插件问题，是 Storybook 自身没注册该 story ID——回头检查文件名、glob 路径、导出名三者是否完全一致
- Webview 不支持 DevTools 调试，真要断点请用
.vscode/launch.json配 Chrome 附加调试，url设为http://localhost:6006，webRoot设为"${workspaceFolder}"
最常被忽略的一点：所有配置都依赖 .storybook/main.js 文件真实存在且语法合法。哪怕多一个逗号，npm run storybook 可能静默失败，终端也不报错，只卡在构建阶段——建议每次改完 main.js 都手动运行一次命令验证。
