跳转到内容

使用环境变量

Astro 使用 Vite 内置支持的环境变量,你可以使用 Vite 的任一方法来处理它们。

注意 虽然 所有 环境变量都对服务端代码可用,但是出于安全考虑,只有以 PUBLIC_ 前缀的环境变量才会对客户端代码可用。

.env
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

在这个示例中,PUBLIC_ANYBODY(通过 import.meta.env.PUBLIC_ANYBODY 访问)将在客户端或服务器端代码中可用,而 SECRET_PASSWORD(通过 import.meta.env.SECRET_PASSWORD 访问)只在服务端可用。

Astro 包括了几个开箱即用的环境变量:

  • import.meta.env.MODEdevelopment | production):站点的运行模式。在运行 astro dev 时为 development,在运行 astro build 时为 production
  • import.meta.env.PRODboolean):当你的站点以production模式运行时为true;否则为false
  • import.meta.env.DEVboolean):当你的站点以development模式运行时为true;否则为false。(总是和 import.meta.env.PROD 相反)。
  • import.meta.env.BASE_URLstring):为站点提供服务的基础 url。它由 base 配置项 决定。
  • import.meta.env.SITEstring):特指项目中 astro.config 中的 site
  • import.meta.env.ASSETS_PREFIXstring):如果设置了 build.assetsPrefix 配置项,则指定 Astro 生成的资源链接的前缀。可以用于创建不由 Astro 处理的资源链接。

你可以将它们当作其他任意的环境变量来使用。

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

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

你也可以在文件名上附加一个模式(productiondevelopment),如 .env.production.env.development,这使得环境变量只在该模式下生效。

只需在项目目录下创建 .env 文件,并在其中添加一些变量。

.env
# 这只有在服务器上运行时才会有效!
DB_PASSWORD="foobar"
# 这在什么地方都有效!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

更多关于.env 文件的信息,请参阅 Vite 文档

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

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

在 Vite 中,你可以使用 import.meta.env,而不是使用 process.env,它使用了 ES2020 中增加的 import.meta 特性。

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

// 当 import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);
// 当 import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

使用 SSR 时,可以根据所使用的 SSR 适配器,在运行时访问环境变量。对于大部分适配器,可以通过 process.env 访问环境变量,但有一些适配器在工作时有所不同。Deno 适配器则需要使用 Deno.env.get()。在使用 Cloudflare 适配器时,可以参阅如何 访问 Cloudflare 运行时 以处理环境变量。Astro 会检查服务器环境中的变量,如果这些变量不存在,则会在 .env 文件中查找它们。

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

当在 .env.[mode] 文件中定义了更多的自定义环境变量,你可能想要得到以 PUBLIC_ 前缀的自定义环境变量的 TypeScript 智能提示。

为了实现这一点,你可以在 src/ 中创建一个 env.d.ts,并配置 ImportMetaEnv

src/env.d.ts
interface ImportMetaEnv {
readonly DB_PASSWORD: string;
readonly PUBLIC_POKEAPI: string;
// 更多环境变量…
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}