环境变量

你可以在 Storybook 中使用环境变量来更改其在不同“模式”下的行为。如果你提供以 STORYBOOK_ 为前缀的环境变量，它将在使用 Webpack 时在 process.env 中可用，或者在使用 Vite 构建器时在 import.meta.env 中可用：

¥You can use environment variables in Storybook to change its behavior in different “modes”. If you supply an environment variable prefixed with STORYBOOK_, it will be available in process.env when using Webpack, or import.meta.env when using the Vite builder:

STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook

不要在 Storybook 中存储任何机密（例如私有 API 密钥）或其他类型的敏感信息。环境变量嵌入到构建中，这意味着任何人都可以通过检查你的文件来查看它们。

¥Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files.

然后我们可以在预览 JavaScript 代码中的任何位置访问这些环境变量，如下所示：

¥Then we can access these environment variables anywhere inside our preview JavaScript code like below:

console.log(process.env.STORYBOOK_THEME);
console.log(process.env.STORYBOOK_DATA_KEY);

你还可以使用替换 %STORYBOOK_X% 在你的自定义 <head>/<body> 中访问这些变量，例如：%STORYBOOK_THEME% 将成为 red。

¥You can also access these variables in your custom <head>/<body> using the substitution %STORYBOOK_X%, for example: %STORYBOOK_THEME% will become red.

如果在 JavaScript 中使用环境变量作为属性或值，则可能需要添加引号，因为值将直接插入，例如：<link rel="stylesheet" href="%STORYBOOK_STYLE_URL%" />。

¥If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly, for example: <link rel="stylesheet" href="%STORYBOOK_STYLE_URL%" />.

使用 .env 文件

¥Using .env files

你还可以使用 .env 文件在不同模式下更改 Storybook 的行为。例如，如果你将 .env 文件添加到你的项目中，内容如下：

¥You can also use .env files to change Storybook's behavior in different modes. For example, if you add a .env file to your project with the following:

STORYBOOK_DATA_KEY=12345

然后你可以在任何地方访问此环境变量，甚至在你的故事中：

¥Then you can access this environment variable anywhere, even within your stories:

MyComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const ExampleStory: Story = {
  args: {
    propertyA: process.env.STORYBOOK_DATA_KEY,
  },
};

使用 Vite

¥With Vite

开箱即用，Storybook 提供了 Vite 构建器，它不会像 process.env 那样输出 Node.js 全局变量。要访问 Storybook 中的环境变量（例如 STORYBOOK_、VITE_），你可以使用 import.meta.env。例如：

¥Out of the box, Storybook provides a Vite builder, which does not output Node.js globals like process.env. To access environment variables in Storybook (e.g., STORYBOOK_, VITE_), you can use import.meta.env. For example:

MyComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const ExampleStory: Story = {
  args: {
    propertyA: import.meta.env.STORYBOOK_DATA_KEY,
    propertyB: import.meta.env.VITE_CUSTOM_VAR,
  },
};

你还可以将特定文件用于特定模式。添加 .env.development 或 .env.production 以将不同的值应用于你的环境变量。

¥You can also use specific files for specific modes. Add a .env.development or .env.production to apply different values to your environment variables.

当你使用 build-storybook 进行构建你的 Storybook 时，你还可以传递这些环境变量。

¥You can also pass these environment variables when you are building your Storybook with build-storybook.

然后它们将被硬编码到 Storybook 的静态版本中。

¥Then they'll be hardcoded to the static version of your Storybook.

使用 Storybook 配置

¥Using Storybook configuration

此外，你可以扩展 Storybook 配置文件（即 .storybook/main.js|.ts）并提供可用于定义特定变量（例如 API URL）的配置字段。例如：

¥Additionally, you can extend your Storybook configuration file (i.e., .storybook/main.js|.ts) and provide a configuration field that you can use to define specific variables (e.g., API URLs). For example:

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  /*
   * 👇 The `config` argument contains all the other existing environment variables.
   * Either configured in an `.env` file or configured on the command line.
   */
  env: (config) => ({
    ...config,
    EXAMPLE_VAR: 'An environment variable configured in Storybook',
  }),
};
 
export default config;

当 Storybook 加载时，它将使你能够像使用 env 文件一样在故事中访问它们：

¥When Storybook loads, it will enable you to access them in your stories similar as you would do if you were working with an env file:

MyComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const Default: Story = {
  args: {
    exampleProp: process.env.EXAMPLE_VAR,
  },
};

使用环境变量选择浏览器

¥Using environment variables to choose the browser

Storybook 允许你选择要预览故事的浏览器。通过 .env 文件条目或直接在你的 storybook 脚本中。

¥Storybook allows you to choose the browser you want to preview your stories. Either through a .env file entry or directly in your storybook script.

下表列出了可用的选项：

¥The table below lists the available options:

浏览器	示例
Safari	`BROWSER="safari"`
Firefox	`BROWSER="firefox"`
Chromium	`BROWSER="chromium"`

默认情况下，Storybook 将在其启动过程中打开一个新的 Chrome 窗口。如果你没有安装 Chrome，请确保包含以下选项之一，或相应地设置你的默认浏览器。

¥By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly.

故障排除

¥Troubleshooting

环境变量不起作用

¥Environment variables are not working

如果你尝试使用特定于框架的环境变量（例如 VUE_APP_），你可能会遇到问题，主要是因为 Storybook 和你的框架可能具有特定的配置，并且可能无法识别和使用这些环境变量。如果你遇到类似情况，你可能需要调整框架配置以确保它可以识别和使用这些环境变量。例如，如果你正在使用基于 Vite 的框架，则可以扩展配置文件并启用 envPrefix 选项。其他框架可能需要类似的方法。

¥If you're trying to use framework-specific environment variables (e.g.,VUE_APP_), you may run into issues primarily due to the fact that Storybook and your framework may have specific configurations and may not be able to recognize and use those environment variables. If you run into a similar situation, you may need to adjust your framework configuration to make sure that it can recognize and use those environment variables. For example, if you're working with a Vite-based framework, you can extend the configuration file and enable the envPrefix option. Other frameworks may require a similar approach.