Переменные окружения

Next.js поставляется с встроенной поддержкой переменных окружения, которая позволяет вам выполнять следующие действия:

• Использование .env.local для загрузки переменных окружения
• Сборка переменных окружения для браузера с помощью префикса NEXT_PUBLIC_

Загрузка переменных окружения

Next.js имеет встроенную поддержку загрузки переменных окружения из .env.local в process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Это автоматически загружает process.env.DB_HOST, process.env.DB_USER, и process.env.DB_PASS в среду Node.js, позволяя использовать их в методах извлечения данных Next.js и маршрутах API.

Например, используя getStaticProps:

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Ссылка на другие переменные

Next.js автоматически расширит переменные, использующие $ для ссылки на другие переменные, например, $VARIABLE в ваших файлах .env*. Это позволяет ссылаться на другие секреты. Например:

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

В приведенном выше примере process.env.TWITTER_URL будет установлено в https://twitter.com/nextjs.

Важно знать: Если вам нужно использовать переменную с $ в фактическом значении, необходимо выполнить экранирование, например, \$.

Сборка переменных окружения для браузера

Переменные окружения, не являющиеся NEXT_PUBLIC_, доступны только в среде Node.js, а значит, они недоступны для браузера (клиент работает в другой среде).

Для того, чтобы значение переменной окружения стало доступным в браузере, Next.js может «встроить» значение во время сборки в js-сборку, которая передается клиенту, заменив все ссылки на process.env.[variable] жёстко закодированным значением. Для этого нужно просто добавить префикс к переменной NEXT_PUBLIC_. Например:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Это указывает Next.js на замену всех ссылок на process.env.NEXT_PUBLIC_ANALYTICS_ID в среде Node.js значением из среды, в которой выполняется next build, что позволяет использовать его где угодно в вашем коде. Он будет встроен в любой JavaScript, отправленный браузеру.

Примечание: После сборки приложение больше не будет реагировать на изменения этих переменных окружения. Например, если вы используете Heroku-пайплайн для продвижения сборок, созданных в одной среде в другую среду, или если вы собираете и развёртываете один Docker-образ в несколько сред, все переменные NEXT_PUBLIC_ будут заморожены со значением, вычисленным во время сборки, поэтому эти значения должны быть установлены должным образом при сборке проекта. Если вам нужен доступ к значениям среды во время выполнения, вам нужно настроить свой собственный API для их предоставления клиенту (по запросу или при инициализации).

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as it's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hello World</h1>
}
 
export default HomePage

Обратите внимание, что динамические запросы не будут встроенными, например:

// This will NOT be inlined, because it uses a variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
 
// This will NOT be inlined, because it uses a variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Переменные среды во время выполнения

Next.js может поддерживать переменные окружения как во время сборки, так и во время выполнения.

По умолчанию переменные окружения доступны только на сервере. Чтобы сделать переменную окружения доступной в браузере, она должна иметь префикс NEXT_PUBLIC_. Однако эти общедоступные переменные окружения будут встроенными в JavaScript-сборку во время next build.

Для чтения переменных окружения во время выполнения рекомендуется использовать getServerSideProps или постепенную адаптацию App Router. С помощью App Router мы можем безопасно читать переменные окружения на сервере во время динамического рендеринга. Это позволяет вам использовать единый Docker-образ, который можно продвигать через несколько сред с различными значениями.

import { unstable_noStore as noStore } from 'next/cache'
 
export default function Component() {
  noStore()
  // cookies(), headers(), and other dynamic functions
  // will also opt into dynamic rendering, meaning
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE
  // ...
}

Важно знать:

• Вы можете запускать код при запуске сервера, используя функцию register.
• Не рекомендуется использовать параметр runtimeConfig, так как он не работает с режимом автономного вывода. Вместо этого мы рекомендуем постепенную адаптацию App Router.

Переменные окружения по умолчанию

В общем случае нужен только один файл .env.local. Однако иногда вам может потребоваться добавить некоторые значения по умолчанию для development (next dev) или production (next start) среды.

Next.js позволяет устанавливать значения по умолчанию в .env (все среды), .env.development (среда разработки) и .env.production (среда производства).

.env.local всегда переопределяет значения по умолчанию.

Важно знать: файлы .env, .env.development, и .env.production должны быть включены в ваш репозиторий, так как они определяют значения по умолчанию. .env*.local следует добавить в .gitignore, так как эти файлы предназначены для игнорирования. .env.local — место хранения секретов.

Переменные окружения на Vercel

При развертывании вашего приложения Next.js на Vercel, переменные окружения можно настроить в Настройках проекта.

Все типы переменных окружения должны быть настроены там. Даже переменные окружения, используемые в разработке, которые могут быть скачаны на ваш локальный компьютер после.

Если вы настроили Переменные окружения среды разработки, вы можете загрузить их в .env.local для использования на локальном компьютере с помощью следующей команды:

vercel env pull .env.local

Важно знать: При развертывании вашего приложения Next.js на Vercel, ваши переменные окружения в файлах .env* не будут доступны для Edge Runtime, если их имя не имеет префикса NEXT_PUBLIC_. Мы настоятельно рекомендуем управлять переменными окружения в Настройках проекта вместо этого, так как оттуда все переменные окружения доступны.

Переменные окружения среды тестирования

Помимо development и production сред, доступна третья опция: test. Таким же образом, как вы можете установить значения по умолчанию для сред разработки или производства, вы можете сделать то же самое с файлом .env.test для среды testing (хотя этот файл используется не так часто, как два предыдущих). Next.js не будет загружать переменные окружения из .env.development или .env.production в среде testing.

Это полезно при запуске тестов с помощью инструментов, таких как jest или cypress, где вам нужно установить определенные переменные среды только для целей тестирования. Значения по умолчанию для тестов будут загружены, если NODE_ENV установлено в test, хотя обычно вам не нужно делать это вручную, так как инструменты тестирования будут обрабатывать это за вас.

Есть небольшая разница между средой test и средами development и production, которую необходимо учитывать: .env.local не будет загружен, так как вы ожидаете, что тесты будут давать одинаковые результаты для всех. Таким образом, каждый запуск теста будет использовать одни и те же значения по умолчанию для среды, игнорируя ваш файл .env.local (который предназначен для переопределения значения по умолчанию).

Важно знать: аналогично переменным окружения по умолчанию, файл .env.test должен быть включён в ваш репозиторий, но .env.test.local не должен, так как .env*.local предназначены для игнорирования с помощью .gitignore.

При выполнении юнит-тестов вы можете убедиться, что переменные окружения загружаются так же, как и Next.js, используя функцию loadEnvConfig из пакета @next/env.

// The below can be used in a Jest global setup file or similar for your testing set-up
import { loadEnvConfig } from '@next/env'
 
export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Порядок загрузки переменных окружения

Переменные окружения ищутся в следующих местах в порядке очереди, процесс останавливается, как только переменная находится.

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (Не проверяется, когда NODE_ENV равно test.)
4. .env.$(NODE_ENV)
5. .env

Например, если NODE_ENV равно development и вы определили переменную как в .env.development.local, так и в .env, будет использовано значение из .env.development.local.

Важно знать: Допустимые значения для NODE_ENV — production, development и test.

Важно знать

• Если вы используете /src директорию, файлы .env.* должны оставаться в корне вашего проекта.
• Если переменная среды NODE_ENV не задана, Next.js автоматически назначает development при выполнении команды next dev, или production для всех остальных команд.

История версий