Nuxt 3 已于 31 July 2026 结束生命周期
此版本将不再接收错误修复或安全补丁。 升级到 Nuxt 4 或获取 HeroDevs 提供的延长支持

.env

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

Maschinelle Übersetzung ·1 % geprüft

应将此文件添加到 .gitignore 文件中,以避免将密钥推送到您的代码仓库。

开发、构建和生成时

Nuxt CLI 在开发模式下以及运行 nuxt build 和 nuxt generate 时内置了对 dotenv 的支持。

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

.env
MY_ENV_VARIABLE=hello
请注意,从 .env 中删除变量或完全删除 .env 文件,不会取消已设置的值。

自定义文件

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

Terminal
npx nuxt dev --dotenv .env.local

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

在应用程序代码中,应使用 Runtime Config,而不是普通的环境变量。

生产环境

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

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

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

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

  • 可通过终端传递环境变量作为参数:

    $ NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs

  • 可在 shell 配置文件如 .bashrc 或 .profile 中设置环境变量。
  • 许多云服务提供商(如 Vercel、Netlify 和 AWS)在其仪表盘、CLI 工具或配置文件中提供设置环境变量的接口。
runtimeConfig 在生产环境中不会获取名称不以 NUXT_ 开头的环境变量 (/docs/guide/going-further/runtime-config#environment-variables)。

生产预览

对于本地生产预览,我们建议使用 nuxt preview,因为使用此命令时,.env 文件会加载到 process.env 中,以便于使用。请注意,此命令要求在 package 目录中安装依赖项。

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

Terminal
NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs

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

Weitere Informationen findest du unter Docs > Guide > Going Further > Runtime Config.
如果想使用构建时设置的环境变量,但不关心之后更新这些变量(或者只需要在应用内响应式地更新它们),那么 appConfig 可能是更好的选择。您可以在 nuxt.config(使用环境变量)和项目中的 ~/app.config.ts 文件中定义 appConfig。
Weitere Informationen findest du unter Docs > Directory Structure > App Config.