Storybook 页面空白或报错 ERR_CONNECTION_REFUSED，主因是未真正启动服务、端口被占或配置错误；需执行 npm run storybook、检查端口占用、确认 .storybook/main.js 配置正确。
Storybook 启动后页面空白或报错 ERR_CONNECTION_REFUSED
VSCode 本身不运行 Storybook，它只是编辑器；你看到的空白页，大概率是没在终端里真正启动服务，或者端口被占用了。
实操建议：
- 确认已在项目根目录执行了
npm run storybook（或yarn storybook），且终端输出中出现类似Local: http://localhost:6006/的地址 - 检查 VSCode 集成终端是否卡在构建阶段（比如显示
Building preview...超过 90 秒）——这时浏览器刷新会失败，等它完成再访问 - 如果提示
ERR_CONNECTION_REFUSED，先用lsof -i :6006（macOS/Linux）或netstat -ano | findstr :6006（Windows）查端口占用，杀掉对应进程再重试 - 默认端口 6006 可通过
.storybook/main.js中的port配置修改，改完要重启服务
想在 VSCode 里点一下就打开对应 Story，而不是手动切浏览器
VSCode 没有原生 Storybook 集成，但可以靠插件 + 配置实现「跳转即预览」。
实操建议：
- 装官方插件
Storybook for VS Code（作者：storybookjs），它能识别*.stories.tsx文件并提供右键菜单 - 确保项目里已生成
.storybook/main.js，且stories字段路径配置正确（比如../src/**/*.stories.@(js|jsx|ts|tsx)），否则插件找不到 story - 右键组件文件 →
Open Storybook是打开整个 Storybook 页面；Open Story for Current File才会定位到该组件的 story —— 注意区分这两个选项 - 如果跳转后 404，检查 story 文件导出名是否和文件名一致（如
Button.stories.tsx应导出Button），否则 Storybook 无法匹配
修改组件代码后 Storybook 不热更新，要手动刷新
不是 VSCode 的问题，是 Storybook 的 webpack / Vite 配置没生效，或监听范围不对。
实操建议：
- 确认
.storybook/main.js中启用了watchOptions（Vite）或webpackFinal里的watchOptions（Webpack），尤其注意ignored列表别把src目录排除了 - 如果用的是 Vite 构建 Storybook（v7+ 默认），检查
vite.config.ts是否误加了server.hmr.overlay = false这类关闭热更新的配置 - 某些 monorepo 场景下，Storybook 运行在子包里，但组件源码在 workspace 根目录，需在
main.js的stories或refs中显式声明路径映射 - 热更新失效时，终端通常会打印
HMR disconnected或Failed to load module，盯住那一行错误比反复刷新更有用
调试 story 里的交互逻辑，断点进不去
VSCode 调试器默认不连接 Storybook 的运行时上下文，得靠 Chrome DevTools 或 VSCode 的 Debugger for Edge/Chrome 插件配合。
实操建议：
- 不要直接在 TSX 文件里打断点然后点「开始调试」——这起不来，因为没启动调试会话
- 先用 VSCode 安装
Debugger for Chrome（或Edge），然后在.vscode/launch.json里加一个Attach to Storybook配置，目标url设为http://localhost:6006 - 启动 Storybook 后，再在 VSCode 里选这个 launch 配置并点击 ▶️，它会自动 attach 到已打开的浏览器 tab
- 这时在
.stories.tsx里打的断点才有效；注意断点位置必须在实际执行的 JS 代码上（比如事件回调里），而不是顶层变量声明处
事情说清了就结束。最常卡住的地方其实是：你以为 VSCode 在“运行” Storybook，其实它只负责写代码；所有服务、热更新、调试通道，都得靠命令行 + 配置 + 浏览器三方对齐。少一环，就白折腾。
