CLI 选项

Storybook 命令行界面 (CLI) 是用于构建和开发 Storybook 的主要工具。

Storybook 会收集完全匿名的信息，以帮助我们改善用户体验。参与是可选的，如果您不想分享任何信息，您可以选择退出。

CLI 命令

所有以下文档都可通过在 CLI 中运行 storybook --help 获取。

如果您使用的是 npm 而不是 Yarn，将选项传递给这些命令的方式会略有不同。您必须在所有选项前加上 --。例如，npm run storybook build -- -o ./path/to/build --quiet。

`dev`

编译并提供 Storybook 的开发构建版本，可在浏览器中实时反映源代码更改。应在项目根目录运行此命令。

storybook dev [options]

选项包括

选项	描述
`--help`	输出用法信息。 `storybook dev --help`
`-V`, `--version`	输出版本号。 `storybook dev -V`
`-p`, `--port [number]`	运行 Storybook 的端口。 `storybook dev -p 9009`
`--exact-port [number]`	尝试在指定的精确端口号上运行 Storybook。如果端口已被占用，Storybook 将会出错退出。 `storybook dev --exact-port 9009`
`-h`, `--host [string]`	运行 Storybook 的主机。 `storybook dev -h my-host.com`
`-c`, `--config-dir [dir-name]`	Storybook 配置目录。 `storybook dev -c .storybook`
`--loglevel [level]`	控制构建期间的日志级别。可用选项： `silly`, `verbose`, `info` (默认), `warn`, `error`, `silent` `storybook dev --loglevel warn`
`--https`	通过 HTTPS 提供 Storybook。注意：您必须提供自己的证书信息。 `storybook dev --https`
`--ssl-ca`	提供 SSL 证书颁发机构。(使用 --https 时可选，如果使用自签名证书则必需) `storybook dev --ssl-ca my-certificate`
`--ssl-cert`	提供 SSL 证书。(使用 --https 时必需) `storybook dev --ssl-cert my-ssl-certificate`
`--ssl-key`	提供 SSL 密钥。(使用 --https 时必需) `storybook dev --ssl-key my-ssl-key`
`--smoke-test`	成功启动后退出。 `storybook dev --smoke-test`
`--ci`	CI 模式 (跳过交互式提示，不打开浏览器)。 `storybook dev --ci`
`--no-open`	不自动在浏览器中打开 Storybook。 `storybook dev --no-open`
`--quiet`	抑制详细的构建输出。 `storybook dev --quiet`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook dev --debug`
`--debug-webpack`	显示最终的 webpack 配置以用于调试。 `storybook dev --debug-webpack`
`--stats-json [dir-name]`	将 stats JSON 写入磁盘。需要 Webpack `storybook dev --stats-json /tmp/stats`
`--no-version-updates`	跳过 Storybook 的更新检查。 `storybook dev --no-version-updates`
`--docs`	在文档模式下启动 Storybook。在此处了解更多信息：这里。 `storybook dev --docs`
`--initial-path [path]`	配置 Storybook 首次打开浏览器时应打开的 URL。 `storybook dev --initial-path=/docs/getting-started--docs`
`--preview-url [path]`	使用自定义构建的预览 URL 覆盖默认的 Storybook 预览。 `storybook dev --preview-url=http://localhost:1337/external-iframe.html`
`--force-build-preview`	强制构建 Storybook 的预览 iframe。如果您遇到问题，或结合 `--preview-url` 使用以确保预览是最新的，这将非常有用。 `storybook dev --force-build-preview`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook dev --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook dev --enable-crash-reports`

随着 Storybook 8 的发布，移除了 -s CLI 标志。如果您需要提供静态文件，建议改用静态目录。

`build`

编译您的 Storybook 实例，以便可以进行部署。应在项目根目录运行此命令。

storybook build [options]

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook build --help`
`-V`, `--version`	输出版本号。 `storybook build -V`
`-o`, `--output-dir [dir-name]`	存储构建文件的目录。 `storybook build -o /my-deployed-storybook`
`-c`, `--config-dir [dir-name]`	Storybook 配置目录。 `storybook build -c .storybook`
`--loglevel [level]`	控制构建期间的日志级别。可用选项： `silly`, `verbose`, `info` (默认), `warn`, `error`, `silent`。 `storybook build --loglevel warn`
`--quiet`	抑制详细的构建输出。 `storybook build --quiet`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook build --debug`
`--debug-webpack`	显示最终的 webpack 配置以用于调试。 `storybook build --debug-webpack`
`--stats-json [dir-name]`	将 stats JSON 写入磁盘。需要 Webpack `storybook build --stats-json /tmp/stats`
`--docs`	在文档模式下构建 Storybook。在此处了解更多信息：这里。 `storybook build --docs`
`--test`	使用 `test` 选项通过移除不必要的功能来优化 Storybook 的生产构建以提高性能和测试。在此处了解更多信息：这里。 `storybook build --test`
`--preview-url [path]`	使用自定义构建的预览 URL 覆盖默认的 Storybook 预览。 `storybook build --preview-url=http://localhost:1337/external-iframe.html`
`--force-build-preview`	强制构建 Storybook 的预览 iframe。如果您遇到问题，或结合 `--preview-url` 使用以确保预览是最新的，这将非常有用。 `storybook build --force-build-preview`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook build --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook build --enable-crash-reports`

`init`

我们建议新项目使用 create-storybook。init 命令将保留以保持向后兼容性。

将指定版本（例如，@latest, @8, @next）的 Storybook 安装并初始化到您的项目。如果未指定版本，将安装最新版本。请在安装指南中阅读更多信息。

storybook[@version] init [options]

例如，storybook@8.4 init 将在您的项目中安装 Storybook 8.4。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook init --help`
`-b`, `--builder`	定义用于您的 Storybook 实例的构建器。 `storybook init --builder webpack5`
`-f`, `--force`	强制将 Storybook 安装到您的项目，并提示您覆盖现有文件。 `storybook init --force`
`-s`, `--skip-install`	跳过依赖安装步骤。仅在需要手动配置 Storybook 时使用。 `storybook init --skip-install`
`-t`, `--type`	定义用于您的 Storybook 实例的框架。 `storybook init --type solid`
`-y`, `--yes`	跳过交互式提示，并根据指定版本自动安装 Storybook，包括所有功能。 `storybook init --yes`
`--features [...values]`	安装时使用这些功能，跳过提示。支持的值包括 `docs` 和 `test`，用空格分隔。 `storybook init --features docs test`
`--package-manager`	设置安装 Storybook 时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook init --package-manager pnpm`
`--use-pnp`	为 Yarn 启用Plug'n'Play 支持。此选项仅在使用 Yarn 作为包管理器时可用。 `storybook init --use-pnp`
`-p`, `--parser`	设置jscodeshift 解析器。可用的解析器包括 `babel`, `babylon`, `flow`, `ts`, 和 `tsx`。 `storybook init --parser tsx`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook init --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook init --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook init --enable-crash-reports`
`--no-dev`	完成 Storybook 的初始化，但不运行 Storybook 开发服务器。 `storybook init --no-dev`

`add`

安装 Storybook 插件并为您的项目配置。在插件安装指南中阅读更多信息。

storybook add [addon] [options]

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook add --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook migrate --config-dir .storybook`
`--package-manager`	设置安装插件时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook add [addon] --package-manager pnpm`
`-s`, `--skip-postinstall`	跳过后安装配置。仅在需要自己配置插件时使用。 `storybook add [addon] --skip-postinstall`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook add --debug`

`remove`

从您的项目删除 Storybook 插件。在插件安装指南中阅读更多信息。

storybook remove [addon] [options]

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook remove --help`
`--package-manager`	设置删除插件时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook remove [addon]--package-manager pnpm`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook remove --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook remove --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook remove --enable-crash-reports`

`upgrade`

将您的 Storybook 实例升级到指定版本（例如，@latest, @8, @next）。在升级指南中阅读更多信息。

storybook[@version] upgrade [options]

例如，storybook@latest upgrade --dry-run 将对您的项目升级到 Storybook 最新版本进行预演（无实际更改）。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook upgrade --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook upgrade --config-dir .storybook`
`-n`, `--dry-run`	检查版本升级，但不安装。 `storybook upgrade --dry-run`
`-s`, `--skip-check`	升级过程中跳过迁移检查步骤。 `storybook upgrade --skip-check`
`-y`, `--yes`	跳过交互式提示，并自动将 Storybook 升级到最新版本。 `storybook upgrade --yes`
`-f`,`--force`	强制升级，跳过自动阻止检查。 `storybook upgrade --force`
`--package-manager`	设置升级 Storybook 时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook upgrade --package-manager pnpm`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook upgrade --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook upgrade --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook upgrade --enable-crash-reports`

`migrate`

运行提供的 codemod 以确保您的 Storybook 项目与指定版本兼容。在迁移指南中阅读更多信息。

storybook[@version] migrate [codemod] [options]

该命令需要 codemod 名称（例如，csf-2-to-3）作为参数，以便对您的项目应用必要的更改。您可以通过运行 storybook migrate --list 找到可用 codemods 列表。

例如，storybook@latest migrate csf-2-to-3 --dry-run，会检查您的项目以验证 codemod 是否可以在不进行任何更改的情况下应用，并提供受影响文件的报告。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook migrate --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook migrate --config-dir .storybook`
`-n`, `--dry-run`	验证迁移是否存在并显示将对其应用的文件。 `storybook migrate --dry-run`
`-l`, `--list`	显示可用 codemods 列表。 `storybook migrate --list`
`-g`, `--glob`	用于指定应用 codemods 的文件 glob。 `storybook migrate --glob src/*/.stories.tsx`
`-p`, `--parser`	设置jscodeshift 解析器。可用的解析器包括 `babel`, `babylon`, `flow`, `ts`, 和 `tsx`。 `storybook migrate --parser tsx`
`-r`, `--rename [from-to]`	重命名受 codemod 影响的文件，使其包含提供的后缀。 `storybook migrate --rename ".js:.ts"`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook migrate --debug`

`automigrate`

执行标准配置检查，以确定您的 Storybook 项目是否可以自动迁移到指定版本。在迁移指南中阅读更多信息。

storybook[@version] automigrate [fixId] [options]

例如，storybook@latest automigrate --dry-run 会扫描您的项目，查找可以自动应用且无需进行任何更改的潜在迁移。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook automigrate --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook automigrate --config-dir .storybook`
`-n`, `--dry-run`	检查可用迁移，但不应用它们。 `storybook automigrate --dry-run`
`-s`, `--skip-install`	在适用的情况下跳过安装依赖项。 `storybook automigrate --skip-install`
`-y`, `--yes`	自动应用可用迁移，无需提示确认。 `storybook automigrate --yes`
`-l`, `--list`	显示可用自动迁移列表。 `storybook automigrate --list`
`--package-manager`	设置运行自动迁移时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook automigrate --package-manager pnpm`
`--renderer`	指定运行自动迁移时使用的 Storybook 渲染器。对于在同一项目中可以存在多个 Storybook 实例的 monorepo 环境非常有用。 `storybook automigrate --renderer vue`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook automigrate --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook automigrate --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook automigrate --enable-crash-reports`

`doctor`

对您的 Storybook 项目进行健康检查，查找常见问题（例如，重复的依赖项、不兼容的插件或版本不匹配），并提供修复建议。适用于升级 Storybook 版本时。

storybook doctor [options]

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook doctor --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook doctor --config-dir .storybook`
`--package-manager`	设置运行健康检查时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `storybook doctor --package-manager pnpm`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook doctor --debug`

`info`

报告有关您的环境的有用调试信息。有助于在提出问题或进行讨论时提供信息。

storybook info

示例输出

Storybook Environment Info:
 
  System:
    OS: macOS 14.2
    CPU: (8) arm64 Apple M3
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 18.19.0 - ~/.nvm/versions/node/v18.19.0/bin/node
    npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm <----- active
  Browsers:
    Chrome: 120.0.6099.199
  npmPackages:
    @storybook/addon-onboarding: ^1.0.10 => 1.0.10
    @storybook/react: ^7.6.6 => 7.6.6
    @storybook/react-vite: ^7.6.6 => 7.6.6
    storybook: ^7.6.6 => 7.6.6
  npmGlobalPackages:
    chromatic: ^10.2.0 => 10.2.0

`index`

构建一个 index.json 文件，其中列出 Storybook 中的所有故事和文档条目。

storybook index [options]

选项包括

选项	描述
`-o`, `--output-file <file-name>`	输出索引的 JSON 文件
`-c`, `--config-dir <dir-name>`	Storybook 配置目录
`--quiet`	抑制详细的构建输出
`--loglevel <level>`	控制构建期间的日志级别
`--disable-telemetry`	禁用 Storybook 的遥测
`--debug`	在 CLI 中输出更多日志以协助调试。
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告

`sandbox`

使用指定版本（例如，@latest, @8, @next）生成本地沙盒项目，以便根据支持的框架列表测试 Storybook 功能。在提出问题或进行讨论时有助于重现错误。

storybook[@version] sandbox [framework-filter] [options]

例如，storybook@next sandbox 将使用 Storybook 最新的预发布版本生成沙盒。

framework-filter 参数是可选的，可以过滤可用框架列表。例如，storybook@next sandbox react 将只提供生成基于 React 的沙盒。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook sandbox --help`
`-o`, `--output [dir-name]`	配置沙盒项目的位置。 `storybook sandbox --output /my-sandbox-project`
`--no-init`	生成沙盒项目，但不初始化 Storybook。 `storybook sandbox --no-init`
`--debug`	在 CLI 中输出更多日志以协助调试。 `storybook sandbox --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `storybook sandbox --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `storybook sandbox --enable-crash-reports`

如果您正在寻找可用沙盒的托管版本，请访问storybook.new。

`create-storybook`

为了简化创建新 Storybook 项目的过程，提供了名为 create-storybook 的独立 CLI。运行 create storybook 时，npm、pnpm 和 Yarn 等包管理器会执行此命令。您可以指定一个版本（例如，@latest, @8, @next），或者它将默认为最新版本。在安装指南中阅读更多信息。

create storybook[@version] [options]

例如，create storybook@8.6 将在您的项目中安装 Storybook 8.6。

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `create storybook --help`
`-b`, `--builder`	定义用于您的 Storybook 实例的构建器。 `create storybook --builder webpack5`
`-f`, `--force`	强制将 Storybook 安装到您的项目，并提示您覆盖现有文件。 `create storybook --force`
`-s`, `--skip-install`	跳过依赖安装步骤。仅在需要手动配置 Storybook 时使用。 `create storybook --skip-install`
`-t`, `--type`	定义用于您的 Storybook 实例的框架。 `create storybook --type solid`
`-y`, `--yes`	跳过交互式提示，并根据指定版本自动安装 Storybook，包括所有功能。 `create storybook --yes`
`--features [...values]`	安装时使用这些功能，跳过提示。支持的值包括 `docs` 和 `test`，用空格分隔。 `create storybook --features docs test`
`--package-manager`	设置安装 Storybook 时使用的包管理器。可用的包管理器包括 `npm`, `yarn`, 和 `pnpm`。 `create storybook --package-manager pnpm`
`--use-pnp`	为 Yarn 启用Plug'n'Play 支持。此选项仅在使用 Yarn 作为包管理器时可用。 `create storybook --use-pnp`
`-p`, `--parser`	设置jscodeshift 解析器。可用的解析器包括 `babel`, `babylon`, `flow`, `ts`, 和 `tsx`。 `create storybook --parser tsx`
`--debug`	在 CLI 中输出更多日志以协助调试。 `create storybook --debug`
`--disable-telemetry`	禁用 Storybook 的遥测。在此处了解更多信息：这里。 `create storybook --disable-telemetry`
`--enable-crash-reports`	启用向 Storybook 的遥测发送崩溃报告。在此处了解更多信息：这里。 `create storybook --enable-crash-reports`
`--no-dev`	完成 Storybook 的初始化，但不运行 Storybook 开发服务器。 `create storybook --no-dev`