VSCode不运行Storybook，所有预览失败等问题90%源于npm run storybook未成功启动；需确认终端输出Local: http://localhost:6006/，排查端口占用、构建错误、配置路径、HMR监听及隔离性问题。
VSCode 本身不运行 Storybook，所有“预览失败”“跳转空白”“热更新不动”的问题，90% 都是因为 npm run storybook 根本没成功启动——先确认服务跑起来，再谈集成。
npm run storybook 启动后报 ERR_CONNECTION_REFUSED
这不是 VSCode 的错，是本地服务压根没绑定到端口。常见于端口被占、命令卡死或配置未生效。
- 终端执行
npm run storybook后，必须看到类似Local: http://localhost:6006/的输出行；如果卡在Building preview...超过 90 秒，大概率构建失败，检查终端顶部是否有ERROR或依赖缺失提示 - macOS/Linux 运行
lsof -i :6006，Windows 运行netstat -ano | findstr :6006查端口占用，杀掉对应 PID 后重试 -
.storybook/main.js中可改端口（如port: 6007），但改完必须重启服务，VSCode 不会自动感知变更 - 某些 Vite + Storybook v7+ 项目默认用
storybook dev -p 6006，若package.json里还写着旧版start-storybook，会直接报 command not found
装了 Storybook for VS Code 插件却没右键菜单
插件不自动注入菜单，它只根据 .storybook/main.js 的 stories 字段扫描文件路径——路径错、文件名错、导出名错，菜单就消失。
-
stories必须是数组，且 glob 要能覆盖你的文件位置，例如组件在src/components/Button.stories.tsx，则stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)']才有效；写成['./src/**/*']或漏掉**/就扫不到 - 文件名必须严格匹配
.stories.（注意两个点），Button.story.tsx、button.stories.ts、Button.stories.test.tsx全部不识别 - 默认导出名必须和文件 basename 一致：
Button.stories.tsx要export default Button；若用具名导出，需配export const Button = { ... }，否则插件无法关联到Button.tsx - monorepo 中，插件只读取当前工作区根目录下的
.storybook/，子包里的配置无效，得在每个含 Storybook 的包里单独配
修改组件代码后 Storybook 不热更新
不是 VSCode 没保存，是 Storybook 的 HMR（热模块替换）链路断了——Vite 或 Webpack 的监听范围、overlay 设置、甚至 require() 写法都可能让它静默失效。
- Vite 用户重点检查
vite.config.ts：若含server.hmr.overlay = false或server.watch.ignored: [/node_modules/, /dist/]里误加了/src/，HMR 直接关闭 -
.storybook/main.js中确保没覆盖watchOptions，v7+ 默认开启，但手动设成{ ignored: ['**/node_modules/**'] }是安全的；设成{ ignored: ['**'] }就等于关监听 - 禁止在
*.stories.tsx里调用未导出的工具函数、或用require('./utils')动态导入——HMR 只能追踪 ES Module 静态导入链 - 如果用了
preview.js（非preview.ts），检查是否漏了parameters: { docs: { autodocs: true } }等配置，部分参数缺失会导致 HMR 初始化失败
VSCode 侧边栏预览打不开或显示空白
VSCode 的 Webview 只是加载一个已存在的 http://localhost:6006 页面，它不接管服务生命周期。预览失败 = 服务不可达 + 配置未对齐。
- 必须在
.vscode/settings.json里显式写"storybook.previewUrl": "http://localhost:6006"；不配这个，右键 “Open Preview to the Side” 会 fallback 到默认地址，大概率 404 - “Open Story for Current File” 和 “Open Preview to the Side” 是两件事：前者跳转 URL，后者加载整个 Storybook UI；后者依赖前者生成的 URL 正确，所以先确保右键菜单能出来
- Webview 加载缓慢或白屏，先在浏览器里手动打开
http://localhost:6006确认服务可访问；如果浏览器也白屏，问题一定在 Storybook 构建层，不是 VSCode - 某些企业网络策略会拦截
localhost的 WebSocket 连接（HMR 依赖它），此时即使页面渲染出来，改代码也不会刷新——需联系 IT 开放ws://localhost:6006
最常被忽略的一点：Storybook 的隔离性完全由它自己的运行时沙箱保证，VSCode 插件只是个遥控器。哪怕所有跳转、预览、热更都看似正常，只要 .storybook/preview.js 里混入了主应用的全局状态初始化逻辑，组件就不是真隔离——这点没法靠插件检测，得人工 review。
