Svelte配置Storybook添加docs参数后HMR报找不到story错误

几个低级错误直接触发解析失败：

• Api.stories.js里没有导入ApiStories.mdx就直接在docs.page里引用了ApiStories变量，未定义变量直接导致Storybook参数解析崩溃，HMR重载时识别不到对应story
• 故事文件里残留了无意义的文本行stories/introduction#using-args，属于语法错误，直接打断JS执行
• 组件导入错误：引入的是Button.stories故事文件，不是实际的Button.svelte组件
• MDX文件没有加<Meta>标签关联对应故事集，且import语句放在正文中间，不符合MDX解析规范
• 配置顺序问题：viewMode: 'docs'写在docs配置前面，首次加载时docs配置还没初始化就尝试跳转docs页，触发加载失败

1. 重写Api.stories.js #

修正导入路径、删除冗余代码、调整配置顺序，注意根据你自己的文件存放位置调整导入路径：

// 替换成你项目里Button.svelte组件的实际路径，不要导入stories文件
import Button from '../../components/Button.svelte';
// 导入自定义MDX文档，路径匹配你存放ApiStories.mdx的位置
import ApiStories from './ApiStories.mdx';

export default {
  title: 'Example/API',
  component: Button,
  parameters: {
    // 先定义docs配置，再设置默认视图
    docs: {
      page: ApiStories,
    },
    previewTabs: {
      canvas: { hidden: true },
    },
    viewMode: 'docs',
  },
};

const Template = (args) => ({
  Component: Button,
  props: args,  
});

export const Primary = Template.bind({});
Primary.args = {};

2. 调整ApiStories.mdx结构 #

所有import语句和Meta标签必须放在文件最顶部，Meta标签要和CSF里的title对应，修正后：

import { Meta, Story } from "@storybook/addon-docs";

<!-- 关联对应故事集，title和stories文件里的title保持一致 -->
<Meta title="Example/API" />

# Replacing DocsPage with custom `MDX` content

This file is a documentation-only `MDX` file to customize Storybook's DocsPage.
You can expand it with custom code snippets and project-specific descriptions as needed.

## Button
Button is the primary component with four built-in states.
- Primary
- Secondary
- Large
- Small

### Primary
<Story id="example-button--primary" />

### Secondary
<Story id="example-button--secondary" />

### Large
<Story id="example-button--large" />

### Small
<Story id="example-button--small" />

注意：你原来MDX里写的your-directory-button--xxx这类不存在的story id要删掉，不然加载时找不到对应story也会抛错，只保留你项目里实际存在的story id即可。

3. 优化main.js配置 #

你现有的配置基本可用，新增MDX2兼容开关避免版本适配问题：

module.exports = {
  "stories": [
    "../src/**/*.stories.mdx",
    "../src/**/*.stories.@(js|jsx|ts|tsx|svelte)"
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions"
  ],
  "framework": "@storybook/svelte",
  "svelteOptions": {
    "preprocess": require("svelte-preprocess")()
  },
  // 开启MDX2支持，适配7.x版本Storybook
  features: {
    previewMdx2: true
  }
}

4. 清缓存重启 #

删除项目下node_modules/.cache/storybook目录，重新执行Storybook启动命令即可。HMR缓存会残留之前的错误状态，不清理可能改完代码还是报旧错。

内容的提问来源于stack exchange，提问作者Tastr