实验性私有元环境变量内联

类型：boolean
默认：false

¥Type: boolean
Default: false

Added in: astro@5.13.0

Astro 6.0 preview

The behavior enabled by this feature will become the default behavior in Astro 6.0.

You may wish to add this flag whenever it is convenient to do so. You can start enjoying the benefits sooner and will avoid the need to update your project code for the next major Astro version.

Astro 允许你配置 环境变量的类型安全模式，并将通过 astro:env 导入的变量转换为预期类型。这是在 Astro 中使用环境变量的推荐方法，因为它允许你轻松查看和管理变量是公开的还是私密的，在构建时是在客户端可用还是仅在服务器端可用，以及变量值的数据类型。

¥Astro allows you to configure a type-safe schema for your environment variables, and converts variables imported via astro:env into the expected type. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values.

但是，如果需要，你仍然可以通过 process.env 以及直接通过 import.meta.env 访问你的环境变量。在 Astro 5.0 添加 astro:env 之前，这是在 Astro 中使用环境变量的唯一方法。它对 import.meta.env 的处理包含一些原本用于早期 Astro 版本的逻辑，这些逻辑现在已不再需要。

¥However, you can still access your environment variables through process.env as well as import.meta.env directly if needed. This was the only way to use environment variables in Astro before astro:env was added in Astro 5.0, and its handling of import.meta.env includes some logic that was intended for earlier versions of Astro that is no longer necessary.

experimental.staticImportMetaEnv 标志更新了直接访问 import.meta.env 时的行为，使其与 Vite 对环境变量的处理 保持一致，并确保 import.meta.env 值始终内联。

¥The experimental.staticImportMetaEnv flag updates the behavior when accessing import.meta.env directly to align with Vite’s handling of environment variables and ensures that import.meta.env values are always inlined.

目前，非公共环境变量会被替换为对 process.env 的引用。此外，Astro 还可能转换通过 import.meta.env 使用的环境变量的值类型，这可能会导致无法访问某些值，例如字符串 "true"（转换为布尔值）和 "1"（转换为数字）。

¥Currently, non-public environment variables are replaced by a reference to process.env. Additionally, Astro may also convert the value type of your environment variables used through import.meta.env, which can prevent access to some values such as the strings "true" (which is converted to a boolean value), and "1" (which is converted to a number).

experimental.staticImportMetaEnv 标志简化了 Astro 的默认行为，使其更易于理解和使用。Astro 将不再使用 process.env 调用替换任何 import.meta.env 环境变量，也不会强制转换值。

¥The experimental.staticImportMetaEnv flag simplifies Astro’s default behavior, making it easier to understand and use. Astro will no longer replace any import.meta.env environment variables with a process.env call, nor will it coerce values.

要启用此功能，请在 Astro 配置中添加实验性标志：

¥To enable this feature, add the experimental flag in your Astro config:

astro.config.mjs

import { defineConfig } from "astro/config"

export default defineConfig({
  experimental: {
    staticImportMetaEnv: true,
  }
})

用法

¥Usage

启用此实验性标志后，字符串值将不再转换为布尔值或数字，也不会将 import.meta.env 值转换为 process.env 调用。这使 Astro 中 import.meta.env 的行为与 Vite 保持一致。

¥Enabling this experimental flag will no longer convert string values into booleans or numbers, nor turn import.meta.env values into process.env calls. This aligns import.meta.env’s behavior in Astro with Vite.

在未来的主要版本中，Astro 将默认启用此行为，但你可以使用 experimental.staticImportMetaEnv 标志提前启用此行为，并在必要时相应地调用 更新你的项目。

¥In a future major version, Astro will switch to this behavior by default, but you can opt in to the future behavior early using the experimental.staticImportMetaEnv flag and, if necessary, updating your project accordingly.

更新你的项目

¥Updating your project

如果你依赖于强制类型转换，则可能需要更新项目代码以手动应用该转换：

¥If you were relying on coercion, you may need to update your project code to apply it manually:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";

如果你依赖于转换为 process.env 格式，则可能需要更新项目代码以手动应用该转换：

¥If you were relying on the transformation into process.env, you may need to update your project code to apply it manually:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

你可能还需要更新类型：

¥You may also need to update types:

src/env.d.ts

interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}

如果你需要对 Astro 中的环境变量进行更多控制，我们建议你使用 astro:env。

¥If you need more control over environment variables in Astro, we recommend you use astro:env.