CLI 选项
Storybook 命令行接口 (CLI) 是你用来构建和开发 Storybook 的主要工具。
¥The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook.
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] | 控制构建期间的日志记录级别。 可用选项: silly、verbose、info(默认)、warn、error、silentstorybook 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] | 将统计信息 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] | 控制构建期间的日志记录级别。 可用选项: 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] | 将统计信息 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-storybook。init 命令将保持向后兼容。
¥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] | 安装时使用这些功能,跳过提示。支持的值为 docs、test 和 a11y,以空格分隔。storybook init --features docs test a11y |
--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 的信息 |
--loglevel <level> | 控制初始化期间的日志记录级别。 可用选项: trace、debug、info(默认)、warn、error、silentstorybook 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-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 |
--loglevel <level> | 控制插件安装期间的日志记录级别。 可用选项: trace、debug、info(默认)、warn、error、silentstorybook 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 | 设置删除插件时使用的包管理器。 可用的包管理器包括 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)。在 升级指南 中阅读更多内容。
¥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 时使用的包管理器。 可用的包管理器包括 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 的信息 |
-logfile [path] | 运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。storybook upgrade --logfile /tmp/debug-storybook.log |
--loglevel <level> | 定义日志级别:debug、error、info、silent、trace 或 warn(默认值: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-dir | Storybook 配置目录.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 解析器。 可用的解析器包括 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 项目是否可以自动迁移到指定版本。在 迁移指南 中阅读更多内容。
¥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-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 项目执行健康检查以查找常见问题(例如,重复的依赖、不兼容的插件或不匹配的版本)并提供有关如何修复它们的建议。适用于 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-dir | Storybook 配置目录.storybook doctor --config-dir .storybook |
--package-manager | 设置运行健康检查时使用的包管理器 check. 可用的包管理器包括 npm、yarn 和 pnpm.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.0index
构建一个 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] | 安装时使用这些功能,跳过提示。支持的值为 docs、test 和 a11y,以空格分隔。create storybook --features docs test a11y |
--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 的信息 |
--loglevel <level> | 控制初始化期间的日志记录级别。 可用选项: trace、debug、info(默认)、warn、error、silentstorybook init --loglevel debug |
--logfile [path] | 运行结束后,将所有调试日志写入指定文件。如果未提供 [path],则默认使用 debug-storybook.log。storybook init --logfile /tmp/debug-storybook.log |
--no-dev | 无需运行 Storybook 开发服务器即可完成 Storybook 的初始化。create storybook --no-dev |
