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

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

::important
应将此文件添加到你的 [`.gitignore`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/gitignore) 文件中，以避免将机密信息推送到你的仓库。
::

## 开发、构建和生成时

Nuxt CLI 在开发模式下以及运行 [`nuxt build`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/build) 和 [`nuxt generate`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/generate) 时，通过 [c12](https://github.com/unjs/c12) 内置支持 `.env`。

除了任何进程环境变量之外，如果你的项目根目录中存在 `.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/4.x/guide/going-further/runtime-config)，而不是普通的环境变量。
::

## 生产环境

**在服务器构建完成后**，在运行服务器时由你负责设置环境变量。

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

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

既然 `.env` 文件在生产环境中不被使用，你必须使用托管环境提供的工具和方法显式设置环境变量。下面是一些常见的方法：

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

  `$ NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`
- 你可以在类似 `.bashrc` 或 `.profile` 的 shell 配置文件中设置环境变量。
- 许多云服务提供商（例如 Vercel、Netlify 和 AWS）提供通过其控制面板、CLI 工具或配置文件设置环境变量的界面。

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

## 生产预览

对于本地生产预览，我们建议使用 [`nuxt preview`](https://nuxt.zhcndoc.com/docs/4.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/4.x/guide/going-further/runtime-config"}
::

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


## Sitemap

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