使用 Nx 的 nx/storybook:build Executor 构建 Storybook 生产站点完整配置指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本篇技术指南聚焦 Nx 仓库中nx/storybook插件提供的nx/storybook:buildexecutor对应开发模式为nx/storybook:storybook讲解如何在project.json中为其配置 target、产出静态站点并覆盖非 Angular 项目的docsMode文档站点模式、Angular 项目的browserTarget与样式注入等实战配置。读完本文你将掌握在 Nx 工作区中构建 Storybook 生产包dist/storybook/*的完整配置方法理解outputs缓存声明、configurations命名配置的用法并了解该 executor 的底层实现与后续迁移路径。一、认识 nx/storybook:build生产模式静态构建nx/storybook:build是 Nx 工作区中用来以生产模式构建 Storybook的 executor。它由packages/storybook插件注册在 executors.json 中可见其注册信息{ executors: { build: { implementation: ./dist/src/executors/build-storybook/build-storybook.impl, schema: ./dist/src/executors/build-storybook/schema.json, description: Build Storybook. } } }其参数校验定义位于 packages/storybook/src/executors/build-storybook/schema.json从 schema 可以看到该 executor 的核心约束必填项configDirStorybook 配置文件所在目录outputDir构建产物输出目录配合outputs声明即可被 Nx 缓存支持styles、stylePreprocessorOptions、docsMode、loglevel、quiet、webpackStatsJson、debugWebpack、disableTelemetry等可选参数。从实现文件 build-storybook.impl.ts 可以看到它的执行流程先做配置目录存在性检查然后根据已安装的 Storybook 版本8.2.0 及以上从storybook/internal/core-server导入更早版本回退到storybook/core-server调用storybookCore.build({ ...options, mode: static })将NODE_ENV默认置为production构建结束后输出产物路径logger.info(NX Storybook files available in ${buildOptions.outputDir});二、基础用法配置 build-storybook target在 Nx 中executor 通过project.json中的 target 配置被调用。以下是一个最小可用的build-storybooktarget 配置对应ui项目{ ui: { targets: { build-storybook: { executor: nx/storybook:build, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ui, configDir: libs/ui/.storybook }, configurations: { ci: { quiet: true } } } } } }配置要点executor声明使用nx/storybook:buildoutputs声明产物路径为{options.outputDir}这样 Nx 可以将该 task 的产物纳入缓存与远程缓存管理命中缓存时直接恢复产物而无需重跑options.outputDir构建产物的输出目录例如dist/storybook/uioptions.configDirStorybook 配置文件.storybook/main.js、.storybook/preview.js等所在目录这是唯一必填参数configurations.ci命名配置运行时可切换例如--configurationci时附加quiet: true以抑制冗长输出。配置完成后通过 Nx 命令运行该 targetnx run ui:build-storybook由于outputs声明了产物路径重复执行时 Nx 会利用缓存跳过构建若需要强制重建可使用nx run ui:build-storybook --skip-nx-cache。若需要读取额外命名配置可追加--configurationci。三、executor 支持的完整参数说明依据 schema.jsonnx/storybook:build支持以下参数参数类型默认值说明configDirstring—加载 Storybook 配置的目录必填outputDirstring—存放构建产物的目录stylesarray—全局样式参与构建每项可以是字符串路径或{ input, bundleName, inject }对象stylePreprocessorOptionsobject—传给样式预处理器的选项其includePaths为要包含的路径相对工作区根解析docsModebooleanfalse仅使用 addon-docs 构建文档站点docsboolean—以文档模式启动 Storybookloglevelstringinfo日志级别可选silly、verbose、info、warn、error、silentquietboolean—抑制冗长的构建输出webpackStatsJsonboolean/stringfalse将 Webpack Stats JSON 写入磁盘debugWebpackboolean—显示最终 webpack 配置以便调试disableTelemetryboolean—禁用 Storybook 遥测其中styles数组项schema 中的extraEntryPoint定义支持两种形式styles: [ src/styles.css, { input: src/theme.css, bundleName: theme, inject: true } ]bundleName用于给该额外入口命名打包inject默认true控制该 bundle 是否被引用进 HTML。四、非 Angular 项目docsMode 文档站点模式对于非 Angular 项目React、Vue、Web Components 等可以通过将docsMode设为true构建一个仅包含文档的站点配合storybook/addon-docs插件使用。配置示例如下{ storybook: { executor: nx/storybook:build, options: { port: 4400, configDir: libs/ui/.storybook, docsMode: true }, configurations: { ci: { quiet: true } } } }在该模式下Storybook 不会渲染 stories 的画布而是以文档页MDX / 自动生成的 docs 页为主体输出静态站点适合把组件文档直接发布为静态站点。docsMode的默认值为false需要显式开启port在构建场景下主要用于内部启动上下文例如配合调试核心仍是输出静态文件。从源码结构看docsMode会原样透传给 Storybook 核心的build调用见 build-storybook.impl.ts 中对options的展开传递。五、Angular 项目使用原生 storybook/angular:build-storybook对于 Angular 项目Nx 生成的默认配置并不走nx/storybook:build而是直接使用 Storybook 官方的storybook/angular:build-storybookexecutor以便完整复用 Angular builder 的能力如browserTarget、compodoc等。5.1 默认配置{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build, compodoc: false }, configurations: { ci: { quiet: true } } } }要点browserTarget指向项目现有的 Angular 构建 targetngapp:buildStorybook 构建时先据此编译应用compodoc是否运行 Compodoc 生成组件文档默认示例中为false。5.2 修改 browserTarget无 build target 时指向 build-storybook当项目没有独立的buildtarget 时可以把browserTarget指向build-storybook自身让 Storybook 构建自举编译流程{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build-storybook, compodoc: false }, configurations: { ci: { quiet: true } } } }这种写法对没有常规应用构建 target 的库项目尤为实用。从源码佐证看Nx 的 Storybook 工具函数 utilities.ts 在检测项目 targets 时会将storybook/angular:build-storybook与nx/storybook:build均识别为storybookBuildTarget并区分仅官方 Angular application/browser builder 才记录为ngBuildTargetnx/angular:*的打包类 executor 不支持样式与额外选项因此更适合交给 build-storybook 承载这些配置这与通过 browserTarget 切换构建来源的实践相互印证。5.3 添加样式与预处理器选项Angular 项目还可以通过styles数组注入全局样式并通过stylePreprocessorOptions.includePaths指定预处理器如 SCSS的额外查找路径用法与 Angular builder 保持一致{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build-storybook, compodoc: false, styles: [some-styles.css], stylePreprocessorOptions: { includePaths: [some-style-paths] } }, configurations: { ci: { quiet: true } } } }注意styles与stylePreprocessorOptions在nx/storybook:buildschema.json 中同样定义与storybook/angular:build-storybook中均可使用但后者依赖 Angular builder 的样式解析管线路径解析与 Angular 构建保持一致。六、底层实现与容错机制两个 executor 的核心实现都在packages/storybook/src/executors/下build-storybook.impl.ts构建实现mode: staticNODE_ENV默认productionstorybook.impl.ts开发服务器实现mode: devNODE_ENV默认development并回传port与baseUrl供下游使用。两者在启动前都会调用storybookConfigExistsCheck(configDir, projectName)定义于 utilities.ts如果configDir不存在或不是目录会抛出带指引的错误Could not find Storybook configuration for project project. Please generate Storybook configuration using the following command: nx g nx/storybook:configuration --nameproject这意味着 target 中的configDir必须指向一个真实存在的.storybook目录未生成配置前应先执行nx g nx/storybook:configuration生成。七、已知弃用与迁移建议需要特别留意的是nx/storybook:build与nx/storybook:storybook这两个 executor 当前已被标记为弃用计划在 Nx v24 中移除。弃用声明同时存在于 schema.json 与 deprecation.ts 中The nx/storybook:build executor is deprecated and will be removed in Nx v24. Run nx g nx/storybook:convert-to-inferred to migrate to the nx/storybook/plugin inferred targets.对应地运行这两个 executor 时也会输出警告日志见 deprecation.ts 中的STORYBOOK_EXECUTOR_DEPRECATION_MESSAGE与STORYBOOK_BUILD_EXECUTOR_DEPRECATION_MESSAGE。官方推荐的迁移方式是执行nx g nx/storybook:convert-to-inferred该生成器源码位于 packages/storybook/src/generators/convert-to-inferred会将显式的 executor target 转换为nx/storybook/plugin推断出的 target。以 build 目标为例其转换逻辑build-post-target-transformer.ts会从原 target 的options中读取configDir缺省时按{projectRoot}/.storybook推断将options与各命名configurations中的属性如docsMode、staticDir迁移到 Storybook 的配置文件main.ts/vite.config等中让 target 改由插件自动推断管理。因此在新建配置时应优先考虑直接使用推断式插件阅读历史项目或旧文档时则需理解本文上述 executor 配置的语义以便顺利完成迁移。八、小结nx/storybook:build提供了一条将 Storybook 构建为生产静态站点的标准化路径通过outputs声明接入 Nx 缓存体系通过configDir/outputDir控制输入输出通过configurations定义 CI 等场景的变体非 Angular 项目可用docsMode输出纯文档站点Angular 项目则建议走storybook/angular:build-storybook并善用browserTarget与styles/stylePreprocessorOptions。同时要留意其已进入弃用窗口新项目应使用nx/storybook/plugin推断 target存量配置可通过nx g nx/storybook:convert-to-inferred平滑迁移。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 9:17:13 · 阅读 1.2k 使用 Nx 的 @nx/storybook:build Executor 构建 Storybook 生产站点：完整配置指南
使用 Nx 的 nx/storybook:build Executor 构建 Storybook 生产站点完整配置指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本篇技术指南聚焦 Nx 仓库中nx/storybook插件提供的nx/storybook:buildexecutor对应开发模式为nx/storybook:storybook讲解如何在project.json中为其配置 target、产出静态站点并覆盖非 Angular 项目的docsMode文档站点模式、Angular 项目的browserTarget与样式注入等实战配置。读完本文你将掌握在 Nx 工作区中构建 Storybook 生产包dist/storybook/*的完整配置方法理解outputs缓存声明、configurations命名配置的用法并了解该 executor 的底层实现与后续迁移路径。一、认识 nx/storybook:build生产模式静态构建nx/storybook:build是 Nx 工作区中用来以生产模式构建 Storybook的 executor。它由packages/storybook插件注册在 executors.json 中可见其注册信息{ executors: { build: { implementation: ./dist/src/executors/build-storybook/build-storybook.impl, schema: ./dist/src/executors/build-storybook/schema.json, description: Build Storybook. } } }其参数校验定义位于 packages/storybook/src/executors/build-storybook/schema.json从 schema 可以看到该 executor 的核心约束必填项configDirStorybook 配置文件所在目录outputDir构建产物输出目录配合outputs声明即可被 Nx 缓存支持styles、stylePreprocessorOptions、docsMode、loglevel、quiet、webpackStatsJson、debugWebpack、disableTelemetry等可选参数。从实现文件 build-storybook.impl.ts 可以看到它的执行流程先做配置目录存在性检查然后根据已安装的 Storybook 版本8.2.0 及以上从storybook/internal/core-server导入更早版本回退到storybook/core-server调用storybookCore.build({ ...options, mode: static })将NODE_ENV默认置为production构建结束后输出产物路径logger.info(NX Storybook files available in ${buildOptions.outputDir});二、基础用法配置 build-storybook target在 Nx 中executor 通过project.json中的 target 配置被调用。以下是一个最小可用的build-storybooktarget 配置对应ui项目{ ui: { targets: { build-storybook: { executor: nx/storybook:build, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ui, configDir: libs/ui/.storybook }, configurations: { ci: { quiet: true } } } } } }配置要点executor声明使用nx/storybook:buildoutputs声明产物路径为{options.outputDir}这样 Nx 可以将该 task 的产物纳入缓存与远程缓存管理命中缓存时直接恢复产物而无需重跑options.outputDir构建产物的输出目录例如dist/storybook/uioptions.configDirStorybook 配置文件.storybook/main.js、.storybook/preview.js等所在目录这是唯一必填参数configurations.ci命名配置运行时可切换例如--configurationci时附加quiet: true以抑制冗长输出。配置完成后通过 Nx 命令运行该 targetnx run ui:build-storybook由于outputs声明了产物路径重复执行时 Nx 会利用缓存跳过构建若需要强制重建可使用nx run ui:build-storybook --skip-nx-cache。若需要读取额外命名配置可追加--configurationci。三、executor 支持的完整参数说明依据 schema.jsonnx/storybook:build支持以下参数参数类型默认值说明configDirstring—加载 Storybook 配置的目录必填outputDirstring—存放构建产物的目录stylesarray—全局样式参与构建每项可以是字符串路径或{ input, bundleName, inject }对象stylePreprocessorOptionsobject—传给样式预处理器的选项其includePaths为要包含的路径相对工作区根解析docsModebooleanfalse仅使用 addon-docs 构建文档站点docsboolean—以文档模式启动 Storybookloglevelstringinfo日志级别可选silly、verbose、info、warn、error、silentquietboolean—抑制冗长的构建输出webpackStatsJsonboolean/stringfalse将 Webpack Stats JSON 写入磁盘debugWebpackboolean—显示最终 webpack 配置以便调试disableTelemetryboolean—禁用 Storybook 遥测其中styles数组项schema 中的extraEntryPoint定义支持两种形式styles: [ src/styles.css, { input: src/theme.css, bundleName: theme, inject: true } ]bundleName用于给该额外入口命名打包inject默认true控制该 bundle 是否被引用进 HTML。四、非 Angular 项目docsMode 文档站点模式对于非 Angular 项目React、Vue、Web Components 等可以通过将docsMode设为true构建一个仅包含文档的站点配合storybook/addon-docs插件使用。配置示例如下{ storybook: { executor: nx/storybook:build, options: { port: 4400, configDir: libs/ui/.storybook, docsMode: true }, configurations: { ci: { quiet: true } } } }在该模式下Storybook 不会渲染 stories 的画布而是以文档页MDX / 自动生成的 docs 页为主体输出静态站点适合把组件文档直接发布为静态站点。docsMode的默认值为false需要显式开启port在构建场景下主要用于内部启动上下文例如配合调试核心仍是输出静态文件。从源码结构看docsMode会原样透传给 Storybook 核心的build调用见 build-storybook.impl.ts 中对options的展开传递。五、Angular 项目使用原生 storybook/angular:build-storybook对于 Angular 项目Nx 生成的默认配置并不走nx/storybook:build而是直接使用 Storybook 官方的storybook/angular:build-storybookexecutor以便完整复用 Angular builder 的能力如browserTarget、compodoc等。5.1 默认配置{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build, compodoc: false }, configurations: { ci: { quiet: true } } } }要点browserTarget指向项目现有的 Angular 构建 targetngapp:buildStorybook 构建时先据此编译应用compodoc是否运行 Compodoc 生成组件文档默认示例中为false。5.2 修改 browserTarget无 build target 时指向 build-storybook当项目没有独立的buildtarget 时可以把browserTarget指向build-storybook自身让 Storybook 构建自举编译流程{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build-storybook, compodoc: false }, configurations: { ci: { quiet: true } } } }这种写法对没有常规应用构建 target 的库项目尤为实用。从源码佐证看Nx 的 Storybook 工具函数 utilities.ts 在检测项目 targets 时会将storybook/angular:build-storybook与nx/storybook:build均识别为storybookBuildTarget并区分仅官方 Angular application/browser builder 才记录为ngBuildTargetnx/angular:*的打包类 executor 不支持样式与额外选项因此更适合交给 build-storybook 承载这些配置这与通过 browserTarget 切换构建来源的实践相互印证。5.3 添加样式与预处理器选项Angular 项目还可以通过styles数组注入全局样式并通过stylePreprocessorOptions.includePaths指定预处理器如 SCSS的额外查找路径用法与 Angular builder 保持一致{ build-storybook: { executor: storybook/angular:build-storybook, outputs: [{options.outputDir}], options: { outputDir: dist/storybook/ngapp, configDir: apps/ngapp/.storybook, browserTarget: ngapp:build-storybook, compodoc: false, styles: [some-styles.css], stylePreprocessorOptions: { includePaths: [some-style-paths] } }, configurations: { ci: { quiet: true } } } }注意styles与stylePreprocessorOptions在nx/storybook:buildschema.json 中同样定义与storybook/angular:build-storybook中均可使用但后者依赖 Angular builder 的样式解析管线路径解析与 Angular 构建保持一致。六、底层实现与容错机制两个 executor 的核心实现都在packages/storybook/src/executors/下build-storybook.impl.ts构建实现mode: staticNODE_ENV默认productionstorybook.impl.ts开发服务器实现mode: devNODE_ENV默认development并回传port与baseUrl供下游使用。两者在启动前都会调用storybookConfigExistsCheck(configDir, projectName)定义于 utilities.ts如果configDir不存在或不是目录会抛出带指引的错误Could not find Storybook configuration for project project. Please generate Storybook configuration using the following command: nx g nx/storybook:configuration --nameproject这意味着 target 中的configDir必须指向一个真实存在的.storybook目录未生成配置前应先执行nx g nx/storybook:configuration生成。七、已知弃用与迁移建议需要特别留意的是nx/storybook:build与nx/storybook:storybook这两个 executor 当前已被标记为弃用计划在 Nx v24 中移除。弃用声明同时存在于 schema.json 与 deprecation.ts 中The nx/storybook:build executor is deprecated and will be removed in Nx v24. Run nx g nx/storybook:convert-to-inferred to migrate to the nx/storybook/plugin inferred targets.对应地运行这两个 executor 时也会输出警告日志见 deprecation.ts 中的STORYBOOK_EXECUTOR_DEPRECATION_MESSAGE与STORYBOOK_BUILD_EXECUTOR_DEPRECATION_MESSAGE。官方推荐的迁移方式是执行nx g nx/storybook:convert-to-inferred该生成器源码位于 packages/storybook/src/generators/convert-to-inferred会将显式的 executor target 转换为nx/storybook/plugin推断出的 target。以 build 目标为例其转换逻辑build-post-target-transformer.ts会从原 target 的options中读取configDir缺省时按{projectRoot}/.storybook推断将options与各命名configurations中的属性如docsMode、staticDir迁移到 Storybook 的配置文件main.ts/vite.config等中让 target 改由插件自动推断管理。因此在新建配置时应优先考虑直接使用推断式插件阅读历史项目或旧文档时则需理解本文上述 executor 配置的语义以便顺利完成迁移。八、小结nx/storybook:build提供了一条将 Storybook 构建为生产静态站点的标准化路径通过outputs声明接入 Nx 缓存体系通过configDir/outputDir控制输入输出通过configurations定义 CI 等场景的变体非 Angular 项目可用docsMode输出纯文档站点Angular 项目则建议走storybook/angular:build-storybook并善用browserTarget与styles/stylePreprocessorOptions。同时要留意其已进入弃用窗口新项目应使用nx/storybook/plugin推断 target存量配置可通过nx g nx/storybook:convert-to-inferred平滑迁移。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考