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

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' можно использовать здесь, так как он имеет префикс '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)

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

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

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

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

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies(), headers() и другие динамические функции
  // также включат динамический рендеринг, что означает,
  // что эта переменная окружения вычисляется во время выполнения
  const value = process.env.MY_VALUE
  // ...
}

Полезно знать:

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

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

Обычно достаточно одного файла .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 для тестового окружения (хотя он не так распространён, как первые два). 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 для всех других команд.

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