Next.js поддерживает загрузку переменных окружения из .env.local в process.env.
.env.local
DB_HOST=localhostDB_USER=myuserDB_PASS=mypassword
Примечание: Next.js также поддерживает многострочные переменные в файлах .env*:
# .env.local# можно писать с переносами строкPRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----...Kh9NV......-----END DSA PRIVATE KEY-----"# или с `\n` внутри двойных кавычек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, позволяя использовать их в Обработчиках маршрутов.
Например:
app/api/route.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*. Это позволяет ссылаться на другие секреты. Например:
Переменные окружения без префикса NEXT_PUBLIC_ доступны только в окружении Node.js, то есть они недоступны в браузере (клиент работает в другом окружении).
Чтобы сделать значение переменной окружения доступным в браузере, Next.js может "встроить" значение во время сборки в JS-бандл, который доставляется клиенту, заменяя все ссылки на process.env.[variable] на жёстко заданное значение. Для этого нужно просто добавить к переменной префикс NEXT_PUBLIC_. Например:
Terminal
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk
Это укажет Next.js заменить все ссылки на process.env.NEXT_PUBLIC_ANALYTICS_ID в окружении Node.js на значение из окружения, в котором выполняется next build, позволяя использовать его в любом месте вашего кода. Оно будет встроено в любой JavaScript, отправляемый в браузер.
Примечание: После сборки ваше приложение больше не будет реагировать на изменения этих переменных окружения. Например, если вы используете конвейер Heroku для продвижения сборок из одного окружения в другое или развёртываете один Docker-образ в нескольких окружениях, все переменные NEXT_PUBLIC_ будут заморожены со значением, определённым во время сборки, поэтому эти значения должны быть установлены соответствующим образом при сборке проекта. Если вам нужен доступ к значениям окружения во время выполнения, вам придётся создать собственный API для их предоставления клиенту (по запросу или во время инициализации).
pages/index.js
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.envsetupAnalyticsService(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 можно хранить секреты.
При развёртывании приложения Next.js на Vercel переменные окружения можно настроить в настройках проекта.
Там следует настраивать все типы переменных окружения. Даже переменные, используемые в разработке, — их можно загрузить на локальное устройство позже.
Если вы настроили переменные окружения для разработки, их можно загрузить в .env.local для использования на локальной машине с помощью следующей команды:
Terminal
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)}
Переменные окружения ищутся в следующих местах в указанном порядке, поиск прекращается при нахождении переменной.
process.env
.env.$(NODE_ENV).local
.env.local (Не проверяется, если NODE_ENV равен test.)
.env.$(NODE_ENV)
.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 для всех других команд.