Storybook 构建配置指南：build.test.disableAutoDocs 精确控制自动生成的 Docs 文档

导读：在 Storybook 中，Autodocs 会根据组件的 CSF 文件自动生成文档页面。本文讲解如何通过 .storybook/main.(js|ts) 中的 build.test.disableAutoDocs 配置开关来控制 autodocs 是否进入最终构建产物，涵盖完整的配置示例、默认行为、storybook build --test 自动启用机制，并结合本仓库源码剖析其底层生效路径，帮助你在构建体积优化、性能测试与调试场景中精准取舍 Docs 产物。

配置项定位：它属于 build.test 测试构建标志组

disableAutoDocs 不是散落在顶层或 docs 节点下的普通配置，而是 Storybook 面向生产构建（production build）优化而设计的一组「测试构建标志（test build flags）」之一。整个配置组挂在主配置文件 .storybook/main.js / .storybook/main.ts 的 build.test 字段下，其类型定义（TestBuildConfig / TestBuildFlags）可以在 类型定义文件 中查看到完整清单：

export interface TestBuildFlags {
  /** 将 @storybook/blocks 从构建产物中排除（即使它在 preview 中被 import） */
  disableBlocks?: boolean;
  /** 禁用指定 addon */
  disabledAddons?: string[];
  /** 过滤掉 .mdx stories 条目 */
  disableMDXEntries?: boolean;
  /** 覆盖 autodocs 为禁用状态 */
  disableAutoDocs?: boolean;
  /** 覆盖 docgen 为禁用状态 */
  disableDocgen?: boolean;
  /** 覆盖 sourcemap 生成为禁用状态 */
  disableSourcemaps?: boolean;
  /** 覆盖 tree-shaking（死代码消除）为禁用状态 */
  disableTreeShaking?: boolean;
  /** 使用 webpack 时用 ESBuild 压缩 */
  esbuildMinify?: boolean;
}

export interface TestBuildConfig {
  test?: TestBuildFlags;
}

disableAutoDocs 的字面语义是：将 autodocs 覆盖为禁用状态，即阻止「由 Autodocs 特性自动生成」的文档页面被包含到构建产物中。与之配套的是 构建配置文档（原始 snippet），文档中对该选项的说明是：

test.disableAutoDocs：Prevents automatic documentation generated with the autodocs feature from being included in the build.（阻止通过 autodocs 特性自动生成的文档被包含进构建产物）

完整配置示例

下面的配置片段原样出自 docs/_snippets/main-config-test-disable-autodocs.md，展示了在不同模块体系（ESM/TypeScript）与不同框架下的写法。首先是最通用的 CSF 3 写法：

export default {
  // 将 your-framework 替换为你实际使用的框架，如 react-vite、nextjs、vue3-vite 等
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableAutoDocs: false,
    },
  },
};

// 将 your-framework 替换为你实际使用的框架，如 react-vite、nextjs、vue3-vite 等
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableAutoDocs: false,
    },
  },
};

export default config;

CSF Next 实验性语法（defineMain）

如果项目启用了 CSF Next（🧪）写法，则使用各框架 node 入口导出的 defineMain 来包裹配置。以 React 为例：

// 将 your-framework 替换为你实际使用的框架（如 react-vite、nextjs、nextjs-vite）
import { defineMain } from '@storybook/your-framework/node';

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  build: {
    test: {
      disableAutoDocs: false,
    },
  },
});

不同框架对应的 defineMain 导入来源与 framework 字段如下表所示，其余结构（stories、build.test.disableAutoDocs）完全一致：

框架	defineMain 导入来源	framework 字段
React（CSF Next）	@storybook/your-framework/node	@storybook/your-framework
Vue 3	@storybook/vue3-vite/node	@storybook/vue3-vite
Angular	@storybook/angular/node	@storybook/angular
Web Components	@storybook/web-components-vite/node	@storybook/web-components-vite

上述各框架的 CSF Next 变体在 snippet 中均提供了 .ts 与 .js（ESM）两种等价写法。需要注意：

• snippet 中出现的 '@storybook/your-framework'、'@storybook/react-vite/node' 均为文档占位符，落地使用时必须替换为项目真实安装的框架包名；
• stories 数组可按项目实际的 story 目录结构调整；
• 该选项的值是布尔类型，snippet 中演示的 false 是显式保持默认行为（不额外禁用 autodocs）；若要让 autodocs 不进入测试构建，应显式设置为 true，详见下一节的自动启用机制。

默认值与 storybook build --test 自动启用机制

这是理解 disableAutoDocs 的关键：该选项平时默认为 false，但当用户以 --test 标志运行 storybook build 时，整套 test 标志会被自动置为开启。官方配置文档中的提示（main-config-build.mdx）明确说明：

本页文档化的选项会在向 storybook build 命令传入 --test 标志时被自动启用。我们只建议在需要为你的项目关闭某个特定特性、或正在调试某个构建问题时，才去手动覆盖这些选项。

从源码结构看，这套「自动启用」逻辑实现在 common-override-preset.ts 中：

const createTestBuildFeatures = (value: boolean): Required<TestBuildFlags> => ({
  disableBlocks: value,
  disabledAddons: value
    ? ['@storybook/addon-docs', '@storybook/addon-essentials/docs', '@storybook/addon-coverage']
    : [],
  disableMDXEntries: value,
  disableAutoDocs: value,
  disableDocgen: value,
  disableSourcemaps: value,
  disableTreeShaking: value,
  esbuildMinify: value,
});

export const build: PresetProperty<'build'> = async (value, options) => {
  return {
    ...value,
    test: options.test
      ? {
          ...createTestBuildFeatures(!!options.test),
          ...value?.test,
        }
      : createTestBuildFeatures(false),
  };
};

这段代码可以解读出三层含义：

1. 默认（未带 --test）：所有 test 标志统一取 false，autodocs 等特性照常参与构建，即上文 snippet 中 disableAutoDocs: false 所对应的行为；
2. storybook build --test：先通过 createTestBuildFeatures(true) 把所有标志置为 true（此时 autodocs 默认被排除），再用 ...value?.test 将用户在 main 配置中显式写的值合并回来覆盖默认值——这正是官方建议「仅在需要关闭特定特性或调试构建问题时覆盖」的原因：你写的显式值会赢过自动值；
3. 覆盖方式：如果你在测试构建中仍想保留 autodocs（例如验证包含 Docs 的产物），就可以像 snippet 那样显式写 disableAutoDocs: false 覆盖自动开启的状态；反之，若想在普通构建中也剔除自动文档，则应写 disableAutoDocs: true。

源码级原理：配置在构建链路中如何生效

disableAutoDocs 的生效点不止一处，本仓库的实现可以从三个层面印证它的实际作用：

1. 生成 Story Index 时跳过 Docs 条目

核心的 StoryIndexGenerator 在为每个 CSF 文件生成索引条目时，会先判断该文件是否需要挂载一个 docs 条目。相关逻辑见 StoryIndexGenerator.ts：

// 如果以下任一条件成立，就需要给 CSF 文件附加 docs 条目：
//   a) autodocs 全局开启
//   b) 该文件显式启用了 autodocs
const hasAutodocsTag = storyEntries.some((entry) => entry.tags.includes(Tag.AUTODOCS));
const createDocEntry = hasAutodocsTag && !!this.options.docs;

if (createDocEntry && this.options.build?.test?.disableAutoDocs !== true) {
  // 构造 type: 'docs' 的索引条目，并将其插入到 story 条目之前
  return { entries: [docsEntry, ...storyEntries], dependents: [], type: 'stories' };
}

return { entries: storyEntries, dependents: [], type: 'stories' };

即：只有当文件带有 autodocs 标签、全局 docs 配置存在，并且 build.test.disableAutoDocs !== true 时，Story Index 中才会生成 type: 'docs' 的条目。一旦该标志为 true，无论文件是否声明 autodocs 标签，自动文档条目都会被整体跳过——它属于「一刀切」的全局覆盖开关，优先级高于文件级 autodocs 标签。

2. addon-docs 的 docs preset 直接返回 undefined

在 addon-docs 的 preset 中，当该标志为真时，docs preset 的解析结果直接短路：

const docs: PresetProperty<'docs'> = (input = {}, options) => {
  if (options?.build?.test?.disableAutoDocs) {
    return undefined;
  }
  // 否则合并默认名 'Docs' 与用户的 docsMode ...
};

docs preset 返回 undefined，意味着 docs 相关配置不被装配，进一步保证了 autodocs 生成的文档不会进入最终构建产物，与 Story Index 层的跳过逻辑形成双重保障。

3. 类型契约约束配置形态

build.test.disableAutoDocs 接收布尔值，其契约位于 core-common.ts 的类型定义。该接口同时被 preset 系统、配置校验与文档自动生成所引用，保证你在 .storybook/main.js|ts 中书写该字段时能获得类型提示与校验。

与同组其他构建标志的关系与选型建议

disableAutoDocs 不是孤立选项，理解它建议同时对照整个 test 标志组在测试/性能构建中的分工（依据 main-config-build.mdx 及上述类型定义）：

标志	作用	关闭对象
disableBlocks	将 @storybook/addon-docs/blocks（Docs Blocks 依赖）排除出 bundle	文档块相关产物
disabledAddons	指定在构建产物中禁用的 addon 列表	addon（含 @storybook/addon-docs 等）
disableMDXEntries	移除用户手写的 MDX 格式文档条目	手写 MDX 文档
disableAutoDocs	覆盖 autodocs 为禁用，阻止自动生成的文档进入构建	自动生成 Docs
disableDocgen	关闭 docgen（默认连带关闭 reactDocgen 与类型检查 check）	属性文档生成
disableSourcemaps	关闭 sourcemap 生成	sourcemap
disableTreeShaking	关闭 tree-shaking（死代码消除）	优化过程

实际使用时的选型判断可以这样落地：

• 什么时候该用：以 storybook build --test 构建“最小化”产物用于性能/加载基准测试时，系统会自动开启本组全部标志，无需手动配置；disableAutoDocs 是其中决定 Docs 文档是否参与构建的关键一项；
• 什么时候显式覆盖：如你的基准测试必须包含 Docs 页面形态，或怀疑 Docs 相关产物在测试构建中被误排除、需要调试构建产物，此时才在 main 配置中显式书写该标志（值为 false 表示放行，true 表示排除）；
• 与手写 MDX 的关系：disableAutoDocs 只管「自动生成」的文档，build.test 组中还提供了 disableMDXEntries 用于过滤「手写 MDX」条目，两者互补而非替代（MDX 条目的过滤逻辑同样见 common-override-preset.ts）；
• 与文件级 autodocs 的关系：日常开发中不希望在某个组件上生成自动文档时，更细粒度的做法仍是控制该文件的 autodocs 标签/全局 docs 配置；而 disableAutoDocs 是面向「整次构建」的全局开关，从 StoryIndexGenerator.ts 的判定顺序可以看出，它生效于索引生成阶段，优先级覆盖所有文件级声明。

常见误区与排障提示

1. 误以为 false 代表“禁用”：该字段为布尔开关，true 才表示排除 autodocs。官方 snippet 中以 false 演示的是“显式保持默认（放行）”的写法，落地时按需取值，不要照抄后误以为已关闭自动文档；
2. 在普通构建中看不到效果：普通 storybook build（不带 --test）下该组标志默认为 false，此时手动在配置里写 false 不会产生可观察差异；要验证效果应显式写 true，或用 --test 构建并覆盖；
3. 排查是否真的生效：可以先对比 disableAutoDocs: true / false 两次构建的产物中是否还包含对应组件的 Docs 页面；若配置不生效，优先检查 .storybook/main.js 的配置文件是否被正确加载、build.test 层级是否嵌套正确；
4. 确认自动文档“究竟是谁生成的”：先判断目标是 Autodocs（由组件 CSF 自动生成）还是手写 MDX（独立 .mdx 文档）。两者在构建产物中的处理路径不同，分别对应 disableAutoDocs 与 disableMDXEntries，混淆二者是常见的配置无效根因。

整体而言，build.test.disableAutoDocs 是 Storybook 在「测试/性能构建」语境下对自动文档产物的一级总开关：理解它与 storybook build --test 的联动关系、与文件级 autodocs 标签及 MDX 文档的边界，即可在构建体积控制与 Docs 功能保留之间做出精确取舍。