使用环境变量

Astro 使用 Vite 内置的环境变量支持，这些变量在构建时被静态替换，并允许你使用它们。

¥Astro uses Vite’s built-in support for environment variables, which are statically replaced at build time, and lets you use any of its methods to work with them.

请注意，虽然所有环境变量在服务器端代码中都可用，但出于安全目的，只有前缀为 PUBLIC_ 的环境变量在客户端代码中可用。

¥Note that while all environment variables are available in server-side code, only environment variables prefixed with PUBLIC_ are available in client-side code for security purposes.

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

在此示例中，PUBLIC_ANYBODY（可通过 import.meta.env.PUBLIC_ANYBODY 访问）将在服务器或客户端代码中可用，而 SECRET_PASSWORD（可通过 import.meta.env.SECRET_PASSWORD 访问）仅在服务器端可用。

¥In this example, PUBLIC_ANYBODY (accessible via import.meta.env.PUBLIC_ANYBODY) will be available in server or client code, while SECRET_PASSWORD (accessible via import.meta.env.SECRET_PASSWORD) will be server-side only.

默认环境变量

¥Default environment variables

Astro 包含一些开箱即用的环境变量：

¥Astro includes a few environment variables out-of-the-box:

import.meta.env.MODE：你的网站运行的模式。运行 astro dev 时为 development，运行 astro build 时为 production。
import.meta.env.PROD：true（如果你的站点正在生产中运行）；否则为 false。
import.meta.env.DEV：true（如果你的网站正在开发中）；否则为 false。始终与 import.meta.env.PROD 相反。
import.meta.env.BASE_URL：为你的网站提供服务的基本网址。这是由 base 配置选项决定的。
import.meta.env.SITE：这被设置为项目的 astro.config 中指定的 site 选项。
import.meta.env.ASSETS_PREFIX：如果设置了 build.assetsPrefix config option，则为 Astro 生成的资源链接的前缀。这可用于创建 Astro 不处理的资源链接。

像任何其他环境变量一样使用它们。

¥Use them like any other environment variable.

const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;

设置环境变量

¥Setting environment variables

`.env` 文件

¥.env files

环境变量可以从项目目录中的 .env 文件加载。

¥Environment variables can be loaded from .env files in your project directory.

你还可以将模式（production 或 development）附加到文件名，例如 .env.production 或 .env.development，这使得环境变量仅在该模式下生效。

¥You can also attach a mode (either production or development) to the filename, like .env.production or .env.development, which makes the environment variables only take effect in that mode.

只需在项目目录中创建一个 .env 文件并添加一些变量即可。

¥Just create a .env file in the project directory and add some variables to it.

# This will only be available when run on the server!
DB_PASSWORD="foobar"
# This will be available everywhere!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

有关 .env 文件的更多信息，请参阅参见 Vite 文档。

¥For more on .env files, see the Vite documentation.

使用 CLI

¥Using the CLI

你还可以在运行项目时添加环境变量：

¥You can also add environment variables as you run your project:

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev

获取环境变量

¥Getting environment variables

Astro 中的环境变量通过 import.meta.env 访问，使用 import.meta feature added in ES2020，而不是 process.env。

¥Environment variables in Astro are accessed with import.meta.env, using the import.meta feature added in ES2020, instead of process.env.

例如，使用 import.meta.env.PUBLIC_POKEAPI 获取 PUBLIC_POKEAPI 环境变量。

¥For example, use import.meta.env.PUBLIC_POKEAPI to get the PUBLIC_POKEAPI environment variable.

// When import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);

// When import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

使用 SSR 时，可以根据所使用的 SSR 适配器在运行时访问环境变量。对于大多数适配器，你可以使用 process.env 访问环境变量，但某些适配器的工作方式有所不同。对于 Deno 适配器，你将使用 Deno.env.get()。了解如何在使用 Cloudflare 适配器时处理环境变量。Astro 将首先检查服务器环境中的变量，如果它们不存在，Astro 将在 .env 文件中查找它们。

¥When using SSR, environment variables can be accessed at runtime based on the SSR adapter being used. With most adapters you can access environment variables with process.env, but some adapters work differently. For the Deno adapter, you will use Deno.env.get(). See how to access the Cloudflare runtime to handle environment variables when using the Cloudflare adapter. Astro will first check the server environment for variables, and if they don’t exist, Astro will look for them in .env files.

TypeScript 的智能感知

¥IntelliSense for TypeScript

默认情况下，Astro 在 astro/client.d.ts 中提供 import.meta.env 的类型定义。

¥By default, Astro provides type definition for import.meta.env in astro/client.d.ts.

虽然你可以在 .env.[mode] 文件中定义更多自定义环境变量，但你可能希望为前缀为 PUBLIC_ 的用户定义环境变量获取 TypeScript IntelliSense。

¥While you can define more custom env variables in .env.[mode] files, you may want to get TypeScript IntelliSense for user-defined env variables which are prefixed with PUBLIC_.

为此，你可以在 src/ 中创建 env.d.ts 并配置 ImportMetaEnv，如下所示：

¥To achieve this, you can create an env.d.ts in src/ and configure ImportMetaEnv like this:

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}