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

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

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

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

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Примечание: Next.js также поддерживает многострочные переменные внутри ваших файлов .env*:

# .env.local
 
# you can write with line breaks
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"
 
# or with `\n` inside double quotes
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

Примечание: Если вы используете папку /src, обратите внимание, что Next.js будет загружать файлы .env только из родительской папки, а не из папки /src. Это автоматически загружает process.env.DB_HOST, process.env.DB_USER, и process.env.DB_PASS в среду Node.js, что позволяет использовать их в Обработчиках маршрутов.

Например:

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

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

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

Примечание: После сборки ваше приложение больше не будет реагировать на изменения этих переменных окружения. Например, если вы используете Heroku pipeline для продвижения сгенерированных в одной среде slug в другую среду, или если вы собираете и разворачиваете один 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 для всех остальных команд.

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