如何配置Storybook参数，用自定义MDX文件替换自动生成的DocsPage

云原生阿岚

2026-8-19

解决Storybook Docs页面显示自定义MDX文件的问题

要让Docs页面显示你自定义的x.stories.mdx文件，而非自动生成内容，不需要将parameters.docs.page设为null，正确配置方式如下：

方法1：在story.js中关联MDX文件

假设你的文件结构是：

src/components/
├─ x.js
├─ x.stories.js
└─ x.stories.mdx

在x.stories.js中导入你的MDX文件：

import XCustomDocs from './x.stories.mdx';

在默认导出的参数中，将docs.page设置为导入的MDX模块：

import X from './x';
import XCustomDocs from './x.stories.mdx';

export default {
  title: 'Components/X',
  component: X,
  parameters: {
    docs: {
      page: XCustomDocs, // 直接传入MDX模块
    },
  },
};

// 你的故事定义
export const Default = {
  args: { /* 属性配置 */ },
};

配置完成后，点击Canvas会显示x.stories.js里的组件和属性，点击Docs会加载x.stories.mdx的自定义内容。

方法2：以MDX文件作为主文档入口

直接在x.stories.mdx中导入组件和定义故事，同时保留x.stories.js的故事配置：

x.stories.mdx内容示例：

import { Meta, Story, Canvas } from '@storybook/addon-docs';
import X from './x';

<Meta title="Components/X" component={X} />

# X 组件文档

这里写你的自定义文档内容，比如组件说明、使用示例等。

<Canvas>
  <Story name="Default">
    <X /* 这里可以直接设置属性 */ />
  </Story>
</Canvas>

这种方式下，Docs页面会自动使用MDX的内容，Canvas依然会显示x.stories.js中定义的所有故事。