npm run storybook 必须先成功运行，vscode storybook 插件仅是前端界面代理，所有功能依赖其服务启动；需确认终端输出 local: http://localhost:6006/，否则预览、跳转、热更新均失效。
npm run storybook 必须先成功运行
VSCode 里的 Storybook 插件不是启动器，它只是个“前端界面代理”——所有预览、跳转、热更新都依赖 npm run storybook 真正跑起来。没看到终端输出 Local: http://localhost:6006/，后面全白搭。
- 卡在
Building preview超过 90 秒？立刻看终端顶部有没有ERROR或Module not found -
ERR_CONNECTION_REFUSED不是插件问题，是服务根本没绑定端口：macOS/Linux 用lsof -i :6006，Windows 用netstat -ano | findstr :6006查占用进程 - 改过
.storybook/main.js里的port: 6007？必须手动杀掉旧进程再重跑npm run storybook，VSCode 不会自动感知端口变更
Storybook for VS Code 插件右键菜单不显示
菜单消失，基本就是路径、命名、导出三者之一没对上。插件只按 .storybook/main.js 的 stories 字段扫描文件，不认设置、不猜意图。
-
stories必须是数组，且 glob 要能命中真实路径：组件在src/components/Button.stories.tsx，就得写['../src/**/*.stories.@(js|jsx|ts|tsx)']；写成['./src/**/*']或漏掉**/就扫不到 - 文件名必须严格为
*.stories.tsx（两个点）：Button.story.tsx、button.stories.ts、Button.stories.test.tsx全部无效 - 默认导出名必须和文件 basename 一致：
Button.stories.tsx要export default Button；若用具名导出，得写export const Button = { ... }，否则插件无法关联到Button.tsx
Vite 项目中 Storybook 热更新(HMR)失效
改了组件代码，VSCode 预览窗格不动，不是插件没保存，是 Vite 的 HMR 链路断了——监听范围窄、overlay 关了、甚至 require() 写法都可能让它静默失败。
- 检查
.storybook/main.js是否启用了features: { storyStoreV7: true }（v7+ 默认开启），否则旧版 HMR 在 Vite 下大概率不工作 - Vite 构建时若用了
build.rollupOptions.external把 React 或组件库排除了，HMR 会因模块未被纳入监听而失效 - 确保组件源码里没有
require('./xxx')这类 CommonJS 动态引入，Vite 的 HMR 对这类写法支持有限，优先用import
monorepo 中 Storybook 插件找不到组件或配置
插件只读取当前 VSCode 工作区根目录下的 .storybook/，子包里配的 main.js 完全无效。monorepo 不是“自动继承”，得显式告诉插件哪条路径对应哪个包。
- 在 workspace 根目录的
.storybook/main.js里加refs字段，例如：{ 'ui': { title: 'UI Components', url: 'http://localhost:6007' } }，然后单独在packages/ui/.storybook/启动服务 - 如果所有 Storybook 都跑在子包里，推荐把 VSCode 工作区直接打开到该子包目录（而非 monorepo 根目录），避免路径错位
- 插件不支持跨工作区引用：不能指望
packages/ui的插件去读packages/design-system的.stories.tsx
最常被忽略的一点：VSCode 插件本身不处理构建逻辑，它只转发请求、解析路径、匹配导出名。任何“预览空白”“跳转失败”“右键消失”，第一反应不该是换插件或重装，而是确认 npm run storybook 输出是否干净、stories glob 是否真扫到了文件、组件导出名是否和文件名完全一致——这三个点卡住一个，插件就彻底失能。
