Docs
Storybook Docs

CLI 选项

Storybook 命令行接口 (CLI) 是你用来构建和开发 Storybook 的主要工具。

¥The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook.

Storybook 收集完全匿名的数据以帮助我们改善用户体验。参与是可选的,如果你不想分享任何信息,你可以选择 opt-out

¥Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may opt-out if you'd not like to share any information.

CLI 命令

¥CLI commands

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

¥All of the following documentation is available in the CLI by running storybook --help.

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

¥Passing options to these commands works slightly differently if you're using npm instead of Yarn. You must prefix all of your options with --. For example, npm run storybook build -- -o ./path/to/build --quiet.

dev

编译并提供 Storybook 的开发版本,以实时反映浏览器中的源代码更改。它应该从项目的根目录运行。

¥Compiles and serves a development build of your Storybook that reflects your source code changes in the browser in real-time. It should be run from the root of your project.

storybook dev [options]

选项包括:

¥Options include:

选项描述
--help输出使用信息.
storybook dev --help
-V, --version输发布本号.
storybook dev -V
-p, --port [number]移植到运行 Storybook.
storybook dev -p 9009
--exact-port尝试在指定的确切端口号上运行 Storybook。
如果该端口已被使用,Storybook 将退出并显示错误消息。
storybook dev -p 9009 --exact-port
-h, --host [string]用于运行 Storybook 的主机。
storybook dev -h my-host.com
-c, --config-dir [dir-name]Storybook 配置目录.
storybook dev -c .storybook
--loglevel [level]控制构建期间的日志记录级别。
可用选项:sillyverboseinfo(默认)、warnerrorsilent
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
--ciCI 模式(跳过交互式提示,不打开浏览器)。
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]将统计信息 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 的信息
--preview-only跳过 Storybook 管理器的构建过程,并以 "仅限预览版" 模式打开应用,该模式旨在用于 不支持的浏览器
storybook dev --preview-only

随着 Storybook 8 的发布,-s CLI 标志被删除。如果你需要提供静态文件,我们建议改用 静态目录

¥With the release of Storybook 8, the -s CLI flag was removed. We recommend using the static directory instead if you need to serve static files.

build

编译你的 Storybook 实例,以便它可以是 deployed。它应该从项目的根目录运行。

¥Compiles your Storybook instance so it can be deployed. It should be run from the root of your project.

storybook build [options]

选项包括:

¥Options include:

选项描述
-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]控制构建期间的日志记录级别。
可用选项:sillyverboseinfo(默认)、warnerrorsilent
storybook build --loglevel warn
--quiet抑制详细构建输出.
storybook build --quiet
--debug在 CLI 中输出更多日志以协助调试。
storybook build --debug
--debug-webpack显示最终的 webpack 配置以进行调试
storybook build --debug-webpack
--stats-json [dir-name]将统计信息 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 的信息
--preview-only跳过 Storybook 管理器的构建过程,生成一个 "仅限预览版" 应用,该应用旨在用于 不支持的浏览器
storybook build --preview-only

init

我们建议新项目使用 create-storybookinit 命令将保持向后兼容。

¥We recommend create-storybook for new projects. The init command will remain available for backwards compatibility.

在你的项目中安装并初始化指定版本(例如 @latest@8@next)的 Storybook。如果未指定版本,则安装最新版本。在 安装指南 中阅读更多内容。

¥Installs and initializes the specified version (e.g., @latest, @8, @next) of Storybook into your project. If no version is specified, the latest version is installed. Read more in the installation guide.

storybook[@version] init [options]

例如,storybook@8.4 init 会将 Storybook 8.4 安装到你的项目中。

¥For example, storybook@8.4 init will install Storybook 8.4 into your project.

选项包括:

¥Options include:

选项描述
-h, --help输出使用信息.
storybook init --help
-b, --builder定义用于 Storybook 实例的 builder
storybook init --builder webpack5
-f, --force强制将 Storybook 安装到你的项目中,提示你覆盖现有文件。
storybook init --force
-s, --skip-install跳过依赖安装步骤。仅在需要手动配置 Storybook 时使用。
storybook init --skip-install
-t, --type定义用于 Storybook 实例的 framework
storybook init --type solid
-y, --yes跳过交互式提示,并自动按指定版本安装 Storybook,包括所有功能。
storybook init --yes
--features [...values]安装时使用这些功能,跳过提示。支持的值为 docstesta11y,以空格分隔。
storybook init --features docs test a11y
--package-manager设置安装 Storybook 时使用的包管理器。
可用的包管理器包括 npmyarnpnpm
storybook init --package-manager pnpm
--use-pnp为 Yarn 启用 Plug'n'Play 支持。此选项仅在使用 Yarn 作为包管理器时可用。
storybook init --use-pnp
-p, --parser设置 jscodeshift 解析器
可用的解析器包括 babelbabylonflowtstsx
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 的信息
--loglevel <level>控制初始化期间的日志记录级别。
可用选项:tracedebuginfo(默认)、warnerrorsilent
storybook init --loglevel debug
--logfile [path]运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。
storybook init --logfile /tmp/debug-storybook.log
--no-dev无需运行 Storybook 开发服务器即可完成 Storybook 的初始化。
storybook init --no-dev

add

安装 Storybook 插件并为其配置你的项目。在 插件安装指南 中阅读更多内容。

¥Installs a Storybook addon and configures your project for it. Read more in the addon installation guide.

storybook add [addon] [options]

选项包括:

¥Options include:

选项描述
-h, --help输出使用信息.
storybook add --help
-c, --config-dirStorybook 配置目录.
storybook migrate --config-dir .storybook
--package-manager设置安装插件时使用的包管理器。
可用的包管理器包括 npmyarnpnpm
storybook add [addon] --package-manager pnpm
-s, --skip-postinstall跳过安装后配置。仅在需要自行配置插件时使用。
storybook add [addon] --skip-postinstall
--debug在 CLI 中输出更多日志以协助调试。
storybook add --debug
--loglevel <level>控制插件安装期间的日志记录级别。
可用选项:tracedebuginfo(默认)、warnerrorsilent
storybook add [addon] --loglevel debug
--logfile [path]运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。
storybook add [addon] --logfile /tmp/debug-storybook.log

remove

从项目中删除 Storybook 插件。在 插件安装指南 中阅读更多内容。

¥Deletes a Storybook addon from your project. Read more in the addon installation guide.

storybook remove [addon] [options]

选项包括:

¥Options include:

选项描述
-h, --help输出使用信息.
storybook remove --help
--package-manager设置删除插件时使用的包管理器。
可用的包管理器包括 npmyarnpnpm
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)。在 升级指南 中阅读更多内容。

¥Upgrades your Storybook instance to the specified version (e.g., @latest, @8, @next). Read more in the upgrade guide.

storybook[@version] upgrade [options]

例如,storybook@latest upgrade --dry-run 将执行一次试运行(无实际更改),将你的项目升级到最新版本的 Storybook。

¥For example, storybook@latest upgrade --dry-run will perform a dry run (no actual changes) of upgrading your project to the latest version of Storybook.

选项包括:

¥Options include:

选项描述
-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 时使用的包管理器。
可用的包管理器包括 npmyarnpnpm.
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 的信息
-logfile [path]运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。
storybook upgrade --logfile /tmp/debug-storybook.log
--loglevel <level>定义日志级别:debugerrorinfosilenttracewarn(默认值:info
storybook upgrade --loglevel debug

migrate

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

¥Runs the provided codemod to ensure your Storybook project is compatible with the specified version. Read more in the migration guide.

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

该命令需要 codemod 名称(例如 csf-2-to-3)作为参数来将必要的更改应用于你的项目。你可以通过运行 storybook migrate --list 找到可用的 codemods 列表。

¥The command requires the codemod name (e.g., csf-2-to-3) as an argument to apply the necessary changes to your project. You can find the list of available codemods by running storybook migrate --list.

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

¥For example, storybook@latest migrate csf-2-to-3 --dry-run, checks your project to verify if the codemod can be applied without making any changes, providing you with a report of which files would be affected.

选项包括:

¥Options include:

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

automigrate

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

¥Perform standard configuration checks to determine if your Storybook project can be automatically migrated to the specified version. Read more in the migration guide.

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

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

¥For example, storybook@latest automigrate --dry-run scans your project for potential migrations that can be applied automatically without making any changes.

选项包括:

¥Options include:

选项描述
-h, --help输出使用信息.
storybook automigrate --help
-c, --config-dirStorybook 配置目录.
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设置运行自动迁移时使用的包管理器。
可用的包管理器包括 npmyarnpnpm
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 项目执行健康检查以查找常见问题(例如,重复的依赖、不兼容的插件或不匹配的版本)并提供有关如何修复它们的建议。适用于 upgrading Storybook 版本。

¥Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when upgrading Storybook versions.

storybook doctor [options]

选项包括:

¥Options include:

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

info

报告有关你的环境的有用调试信息。有助于在打开问题或讨论时提供信息。

¥Reports useful debugging information about your environment. Helpful in providing information when opening an issue or a discussion.

storybook info

示例输出:

¥Example output:

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 中所有故事和文档条目。

¥Build an index.json that lists all stories and docs entries in your Storybook.

storybook index [options]

选项包括:

¥Options include:

选项描述
-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)生成本地沙盒项目,以根据支持的 frameworks 列表测试 Storybook 功能。适用于打开问题或讨论时重现错误。

¥Generates a local sandbox project using the specified version (e.g., @latest, @8, @next) for testing Storybook features based on the list of supported frameworks. Useful for reproducing bugs when opening an issue or a discussion.

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

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

¥For example, storybook@next sandbox will generated sandboxes using the newest pre-release version of Storybook.

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

¥The framework-filter argument is optional and can filter the list of available frameworks. For example, storybook@next sandbox react will only offer to generate React-based sandboxes.

选项包括:

¥Options include:

选项描述
-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

¥If you're looking for a hosted version of the available sandboxes, see storybook.new.

create-storybook

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

¥To streamline the process of creating a new Storybook project, a separate CLI called create-storybook is provided. Package managers such as npm, pnpm, and Yarn will execute this command when running create storybook. You can specify a version (e.g., @latest, @8, @next) or it will default to the latest version. Read more in the installation guide.

create storybook[@version] [options]

例如,create storybook@8.6 会将 Storybook 8.6 安装到你的项目中。

¥For example, create storybook@8.6 will install Storybook 8.6 into your project.

选项包括:

¥Options include:

选项描述
-h, --help输出使用信息.
create storybook --help
-b, --builder定义用于 Storybook 实例的 builder
create storybook --builder webpack5
-f, --force强制将 Storybook 安装到你的项目中,提示你覆盖现有文件。
create storybook --force
-s, --skip-install跳过依赖安装步骤。仅在需要手动配置 Storybook 时使用。
create storybook --skip-install
-t, --type定义用于 Storybook 实例的 framework
create storybook --type solid
-y, --yes跳过交互式提示,并自动按指定版本安装 Storybook,包括所有功能。
create storybook --yes
--features [...values]安装时使用这些功能,跳过提示。支持的值为 docstesta11y,以空格分隔。
create storybook --features docs test a11y
--package-manager设置安装 Storybook 时使用的包管理器。
可用的包管理器包括 npmyarnpnpm
create storybook --package-manager pnpm
--use-pnp为 Yarn 启用 Plug'n'Play 支持。此选项仅在使用 Yarn 作为包管理器时可用。
create storybook --use-pnp
-p, --parser设置 jscodeshift 解析器
可用的解析器包括 babelbabylonflowtstsx
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 的信息
--loglevel <level>控制初始化期间的日志记录级别。
可用选项:tracedebuginfo(默认)、warnerrorsilent
storybook init --loglevel debug
--logfile [path]运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。
storybook init --logfile /tmp/debug-storybook.log
--no-dev无需运行 Storybook 开发服务器即可完成 Storybook 的初始化。
create storybook --no-dev