---
title: ".env"
description: ".env 文件指定构建/开发时环境变量。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/directory-structure/env"
---
# .env

> .env 文件指定构建/开发时环境变量。

::important
应将此文件添加到 [`.gitignore`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/gitignore) 文件中，以避免将密钥推送到您的代码仓库。
::

## 开发、构建和生成时

Nuxt CLI 在开发模式下以及运行 [`nuxt build`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/build) 和 [`nuxt generate`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/generate) 时内置了对 [dotenv](https://github.com/motdotla/dotenv) 的支持。

除了任何进程环境变量外，如果项目根目录中有 `.env` 文件，它将在 **开发、构建和生成时** 自动加载。此处设置的任何环境变量都可以在 `nuxt.config` 文件和模块中访问。

```ini [.env]
MY_ENV_VARIABLE=hello
```

::note
请注意，从 `.env` 中删除变量或完全删除 `.env` 文件，不会取消已设置的值。
::

## 自定义文件

如果想使用不同的文件——例如 `.env.local` 或 `.env.production`——可以在使用 Nuxt CLI 时传入 `--dotenv` 参数来实现。

```bash [Terminal]
npx nuxt dev --dotenv .env.local
```

开发模式下更新 `.env` 文件时，Nuxt 实例会自动重启，以将新值应用到 `process.env`。

::important
在应用程序代码中，应使用 [Runtime Config](https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/runtime-config)，而不是普通的环境变量。
::

## 生产环境

**服务器构建完成后**，您需在运行服务器时自行设置环境变量。

此时不会读取 `.env` 文件。如何设置取决于不同的环境。

此设计决定确保兼容各种部署环境，其中一些可能没有传统的文件系统，如无服务器平台或像 Cloudflare Workers 这样的边缘网络。

由于生产环境不使用 `.env` 文件，您必须通过托管环境提供的工具和方法显式设置环境变量。常见方式包括：

- 可通过终端传递环境变量作为参数：

  `$ NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`
- 可在 shell 配置文件如 `.bashrc` 或 `.profile` 中设置环境变量。
- 许多云服务提供商（如 Vercel、Netlify 和 AWS）在其仪表盘、CLI 工具或配置文件中提供设置环境变量的接口。

::important
`runtimeConfig` 在生产环境中[不会获取名称不以 `NUXT_` 开头的环境变量] (/docs/guide/going-further/runtime-config#environment-variables)。
::

## 生产预览

对于本地生产预览，我们建议使用 [`nuxt preview`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/preview)，因为使用此命令时，`.env` 文件会加载到 `process.env` 中，以便于使用。请注意，此命令要求在 package 目录中安装依赖项。

或者也可以使用终端通过参数传递环境变量。例如，在 Linux 或 macOS 上：

```bash [Terminal]
NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs
```

请注意，对于纯静态站点，在项目预渲染完成后，无法设置运行时配置。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/runtime-config"}
::

::note
如果想使用构建时设置的环境变量，但不关心之后更新这些变量（或者只需要在应用内响应式地更新它们），那么 `appConfig` 可能是更好的选择。您可以在 `nuxt.config`（使用环境变量）和项目中的 `~/app.config.ts` 文件中定义 `appConfig`。
:read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/app-config"}
::


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.