环境变量

本文档适用于 9.4 和更高版本的 Next.js。如果你使用的是较旧版本的 Next.js,请参阅 next.config.js 中的环境变量

Next.js 内置了对环境变量的支持,让你可以执行以下操作:

内联(inlined)环境变量

Next.js 将在你的应用程序中内联任何以 NEXT_PUBLIC_ 开头的环境变量。内联意味着将变量替换为实际的值。例如,以下页面:

export default function Page() {
  return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1>
}

将变为:

export default function Page() {
  return <h1>The public value is: {'my-value'}</h1>
}

Next.js 将 process.env.NEXT_PUBLIC_EXAMPLE_KEY 替换为其实际值,在此例子中是 'my-value'

你可以使用 shell 或任何其他工具在 Next.js CLI 运行之前来添加环境变量。例如,使用 bash:

NEXT_PUBLIC_EXAMPLE_KEY=my-value npx next dev

或在 Windows 和 Unix 系统中使用 cross-env

npx cross-env NEXT_PUBLIC_EXAMPLE_KEY=my-value next dev

注意事项

  • 由于 webpack 的 DefinePlugin 的限制,不支持对 process.env 变量的解构(destructure)。
  • 为避免安全泄露,请不要使用随意 NEXT_PUBLIC_ 前缀。而应该 使用 .env 暴露环境变量

暴露环境变量

Next.js 允许您使用环境变量文件(.env)暴露变量,并包含对多种环境的支持。像这样:

  • .env - 包含所有环境的环境变量
  • .env.local - 在所有环境下覆盖同名变量的本地变量
  • .env.[environment] - 为某个环境专用的环境变量。例如:.env.development
  • .env.[environment].local - 在某个环境下覆盖同名变量的本地变量。例如:.env.development.local

注意.env 文件 应当 被包含进你的源码仓库中,并且 .env*.local 应被添加到 .gitignore,因为这些文件需要被忽略。建议将 .local 文件作为存放机密信息的地方,而将非 local 文件作为存放默认值的地方。

developmentproductiontest 环境均被支持。环境的选择遵循以下方式:

如果同一个环境变量被多次定义,则按以下顺序确定各变量的优先级:

  • 已经定义的环境变量具有更高的优先级。例如:MY_KEY=value next dev
  • .env.[environment].local
  • .env.local
  • .env.[environment]
  • .env

例如,假设 .env.local 文件包含以下内容:

API_KEY='my-secret-api-key'
NEXT_PUBLIC_APP_LOCALE='en-us'

以及有以下页面:

export default function Page() {
  return <h1>The locale is set to: {process.env.NEXT_PUBLIC_APP_LOCALE}</h1>
}

export async function getStaticProps() {
  const db = await myDB(process.env.API_KEY)
  // ...
}

process.env.NEXT_PUBLIC_APP_LOCALE 将在构建时被替换为 'en-us'。这是因为以 NEXT_PUBLIC_ 开头的变量将 在构建时被内联

process.env.API_KEY 在构建和运行时都将是 'my-secret-api-key' ,但是构建之后的输出中将不包含此变量。这是因为 process.env.API_KEY 仅由 getStaticProps 在服务器端使用 ,只有 getStaticProps 所返回的 props 被包含在构建后的客户端文件中。我们的其它 数据获取方式 也如此。

现在,如果你添加一个如下的 .env 文件的话:

API_KEY='default-api-key'
CLIENT_KEY='default-client-key'
NEXT_PUBLIC_APP_LOCALE='en-us'

API_KEYNEXT_PUBLIC_APP_LOCALE 将被忽略,因为 .env.local 具有较高的优先级,但是 CLIENT_KEY 仍是可用的。