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=https://: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`
`--preview-only`	跳过 Storybook 的管理器构建，并以“仅预览”模式打开应用程序，该模式旨在用于不支持的浏览器。 `storybook dev --preview-only`

随着 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`	通过移除不必要的功能，优化 Storybook 的生产构建以提高性能和测试效果，使用 `test` 选项。在此处了解更多。 `storybook build --test`
`--preview-url [path]`	用自定义构建的预览 URL 覆盖默认的 Storybook 预览。 `storybook build --preview-url=https://: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`
`--preview-only`	跳过 Storybook 的管理器构建，并生成一个“仅预览”应用程序，该应用程序旨在用于不支持的浏览器。 `storybook build --preview-only`

`init`

我们建议新项目使用create-storybook。为了向后兼容，init 命令将继续可用。

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

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 <dir-name...>`	查找 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`
`--write-logs`	在运行结束时将所有调试日志写入文件。 `storybook upgrade --write-logs`
`--loglevel <level>`	定义日志级别：`debug`、`error`、`info`、`silent`、`trace` 或 `warn`（默认：`info`）。 `storybook upgrade --loglevel debug`

`migrate`

运行提供的代码转换器，以确保您的 Storybook 项目与指定版本兼容。在迁移指南中阅读更多内容。

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

该命令需要代码转换器名称（例如 csf-2-to-3）作为参数来应用必要的更改到您的项目。您可以通过运行 storybook migrate --list 来查找可用代码转换器的列表。

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

选项包括

选项	描述
`-h`, `--help`	输出用法信息。 `storybook migrate --help`
`-c`, `--config-dir`	Storybook 配置目录。 `storybook migrate --config-dir .storybook`
`-n`, `--dry-run`	验证迁移是否存在并显示将要应用到的文件。 `storybook migrate --dry-run`
`-l`, `--list`	显示可用代码转换器的列表。 `storybook migrate --list`
`-g`, `--glob`	要应用代码转换器的文件的 glob 模式。 `storybook migrate --glob src/*/.stories.tsx`
`-p`, `--parser`	设置jscodeshift 解析器。可用的解析器包括 `babel`、`babylon`、`flow`、`ts` 和 `tsx`。 `storybook migrate --parser tsx`
`-r`, `--rename [from-to]`	将受代码转换器影响的文件重命名为包含提供的后缀。 `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 实例的单体仓库环境很有用。 `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`

报告有关您环境的有用调试信息。在提交 issue 或讨论时提供信息很有帮助。

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 功能，基于支持的框架列表。在提交 issue 或讨论时，用于重现 bug 很有用。

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 项目的过程，提供了一个独立的 CLI create-storybook。npm、pnpm 和 Yarn 等包管理器在运行 create storybook 时会执行此命令。您可以指定一个版本（例如 @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`