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

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, позволяя использовать их в Route Handlers.

Например:

export async function GET() {
  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.[переменная] на жёстко заданное значение. Для этого нужно просто добавить префикс NEXT_PUBLIC_ к переменной. Например:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

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

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

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID' можно использовать здесь, так как он имеет префикс 'NEXT_PUBLIC_'.
// Во время сборки это будет преобразовано в `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

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

// Это НЕ будет встроено, так как используется переменная
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// Это НЕ будет встроено, так как используется переменная
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

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

Обычно достаточно одного файла .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

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

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

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

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

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

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

// Нижеприведённый код можно использовать в глобальном файле настройки Jest или аналогичном для вашей тестовой среды
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 для всех остальных команд.