安装 Storybook

使用 Storybook CLI 在单个命令中安装它。在项目的根目录中运行此命令：

¥Use the Storybook CLI to install it in a single command. Run this inside your project’s root directory:

npx storybook@latest init

Install a specific version

init 命令将使用你指定的任何版本。例如：

¥The init command will use whichever version you specify. For example:

storybook@latest init 将初始化最新版本

¥storybook@latest init will initialize the latest version
storybook@7.6.10 init 将初始化 7.6.10

¥storybook@7.6.10 init will initialize 7.6.10
storybook@7 init 将初始化最新的 7.x.x 版本

¥storybook@7 init will initialize the newest 7.x.x version

Storybook 将在安装过程中查看项目的依赖，并为你提供最佳可用配置。

¥Storybook will look into your project's dependencies during its install process and provide you with the best configuration available.

上面的命令将对你的本地环境进行以下更改：

¥The command above will make the following changes to your local environment:

📦 安装所需的依赖。

¥📦 Install the required dependencies.
🛠 设置运行和构建 Storybook 所需的脚本。

¥🛠 Setup the necessary scripts to run and build Storybook.
🛠 添加默认的 Storybook 配置。

¥🛠 Add the default Storybook configuration.
📝 添加一些样板故事以帮助你入门。

¥📝 Add some boilerplate stories to get you started.
📡 设置遥测以帮助我们改进 Storybook。阅读有关此处的更多信息。

¥📡 Set up telemetry to help us improve Storybook. Read more about it here.

Watch a video tutorial

运行安装向导

¥Run the Setup Wizard

如果一切顺利，你应该会看到一个安装向导，它将帮助你开始使用 Storybook，向你介绍主要概念和功能，包括 UI 的组织方式、如何编写你的第一个故事以及如何利用 controls 测试组件对各种输入的响应。

¥If all goes well, you should see a setup wizard that will help you get started with Storybook introducing you to the main concepts and features, including how the UI is organized, how to write your first story, and how to test your components' response to various inputs utilizing controls.

Storybook onboarding

如果你跳过了向导，你可以随时通过将 ?path=/onboarding 查询参数添加到 Storybook 实例的 URL 来再次运行它，前提是示例故事仍然可用。

¥If you skipped the wizard, you can always run it again by adding the ?path=/onboarding query parameter to the URL of your Storybook instance, provided that the example stories are still available.

启动 Storybook

¥Start Storybook

Storybook 带有内置开发服务器，具有项目开发所需的一切。根据你的系统配置，运行 storybook 命令将启动本地开发服务器，为你输出地址，并自动在新浏览器选项卡中打开该地址，欢迎屏幕会向你致意。

¥Storybook comes with a built-in development server featuring everything you need for project development. Depending on your system configuration, running the storybook command will start the local development server, output the address for you, and automatically open the address in a new browser tab where a welcome screen greets you.

npm run 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.

Storybook welcome screen

这里有一些值得注意的项目：

¥There are some noteworthy items here:

一组有用的链接，用于你可以使用的更深入的配置和自定义选项。

¥A collection of useful links for more in-depth configuration and customization options you have at your disposal.
第二组链接可让你扩展你的 Storybook 知识并参与不断发展的 Storybook 社区。

¥A second set of links for you to expand your Storybook knowledge and get involved with the ever-growing Storybook community.
一些示例故事可以帮助你入门。

¥A few example stories to get you started.

Troubleshooting

与其他包管理器一起运行 Storybook

¥Run Storybook with other package managers

Storybook CLI 包括对业界流行的包管理器（例如 Yarn、npm 和 pnpm）的支持，可在你初始化 Storybook 时自动检测你正在使用的包管理器。但是，如果你想使用特定的包管理器作为默认包管理器，请在安装命令中添加 --package-manager 标志。例如：

¥The Storybook CLI includes support for the industry's popular package managers (e.g., Yarn, npm, and pnpm) automatically detecting the one you are using when you initialize Storybook. However, if you want to use a specific package manager as the default, add the --package-manager flag to the installation command. For example:

npx storybook@latest init --package-manager=npm

CLI 未检测到我的框架

¥The CLI doesn't detect my framework

如果你正在使用自定义环境设置或需要手动设置 Storybook，则可以使用 --type 标志指定你需要使用的框架。下面列出了支持的框架及其使用示例：

¥If you're working with a custom environment set up or need set up Storybook manually, you can use the --type flag to specify the framework you need to use. Listed below are the supported frameworks and examples of how to use them:

框架	类型
Angular	`angular`
Ember	`ember`
HTML	`html`
Next.js	`nextjs`
Preact	`preact`
Qwik	`qwik`
React	`react`
服务器	`server`
Solid	`solid`
Svelte	`svelte`
Vue 3	`vue3`
Web 组件	`web_components`

npx storybook@latest init --type solid

Yarn Plug'n'Play (PnP) 支持 Storybook

¥Yarn Plug'n'Play (PnP) support with Storybook

如果你在启用了 Plug'n'Play（PnP）的新版本 Yarn 上运行的项目中启用了 Storybook，你可能会注意到它将生成 node_modules 以及一些其他文件和文件夹。这是一个已知的限制，因为 Storybook 依赖某些目录（例如 .cache）来存储缓存文件和其他数据，以提高性能和加快构建速度。你可以安全地忽略这些文件和文件夹，调整你的 .gitignore 文件以将它们从你正在使用的版本控制中排除。

¥If you've enabled Storybook in a project running on a new version of Yarn with Plug'n'Play (PnP) enabled, you may notice that it will generate node_modules with some additional files and folders. This is a known constraint as Storybook relies on some directories (e.g., .cache) to store cache files and other data to improve performance and faster builds. You can safely ignore these files and folders, adjusting your .gitignore file to exclude them from the version control you're using.

使用 Webpack 4 运行 Storybook

¥Run Storybook with Webpack 4

如果你之前在使用 Webpack 4 的项目中安装了 Storybook，它将不再起作用。这是因为 Storybook 现在默认使用 Webpack 5。要解决此问题，我们建议你将项目升级到 Webpack 5，然后运行以下命令将项目迁移到最新版本的 Storybook：

¥If you previously installed Storybook in a project that uses Webpack 4, it will no longer work. This is because Storybook now uses Webpack 5 by default. To solve this issue, we recommend you upgrade your project to Webpack 5 and then run the following command to migrate your project to the latest version of Storybook:

npx storybook@latest automigrate

安装过程似乎不稳定，并且一直失败

¥The installation process seems flaky and keeps failing

如果你在安装过程中仍然遇到一些问题，我们建议你查看以下资源：

¥If you're still running into some issues during the installation process, we encourage you to check out the following resources:

Storybook 的 React Webpack 自述文件了解有关如何使用 Webpack 5 在 React 项目中设置 Storybook 的更多信息。

¥Storybook's React Webpack README for more information on how to set up Storybook in your React project with Webpack 5.
Storybook 的 React Vite 自述文件了解有关如何使用 Vite 在 React 项目中设置 Storybook 的更多信息。

¥Storybook's React Vite README for more information on how to set up Storybook in your React project with Vite.
Storybook 的帮助文档用于联系社区并寻求帮助。

¥Storybook's help documentation to contact the community and ask for help.

现在你已经成功安装了 Storybook 并了解了它的工作原理，让我们继续你在设置向导中离开的地方，更深入地研究编写故事。

¥Now that you have successfully installed Storybook and understood how it works, let's continue where you left off in the setup wizard and delve deeper into writing stories.