Как работать с переменными окружения в Nuxt

Введение

Переменные окружения — один из ключевых инструментов конфигурирования приложений на различных этапах разработки и развертывания. Если вы работаете с Nuxt, то наверняка сталкивались с задачами по настройке API-адресов, хранению секретных ключей или переключению между production и development конфигами. Гибкость работы с переменными окружения позволяет избежать хардкода, повысить безопасность данных и сделать ваш проект намного удобнее для поддержки и масштабирования. В этой статье вы узнаете, как работать с переменными окружения на проектах Nuxt (актуально для Nuxt 2.x и Nuxt 3), какие типичные подходы существуют, как правильно использовать их в коде и какие ошибки стоит избегать.

Концепция переменных окружения в Nuxt

Зачем нужны переменные окружения

Переменные окружения позволяют:

• Разделять конфигурации для разных сред (например, dev, staging, production)
• Не хранить секретные данные в репозитории (API-ключи, токены)
• Переиспользовать проект в разных условиях без изменения исходного кода
• Удалять хардкод из конфигов

В Nuxt переменные окружения используются как на стороне клиента, так и на сервере (особенно если используется серверный рендеринг или серверные модули).

Как задавать переменные окружения в Nuxt

Nuxt поддерживает подгрузку переменных окружения несколькими способами.

Использование файла .env

Наиболее популярный способ — это создать файл с именем .env в корне проекта. Смотрите, как может выглядеть пример такого файла:

# .env
API_URL=https://api.example.com
API_KEY=mySuperSecretToken
DEBUG_MODE=true

Обратите внимание, что здесь переменные задаются строками в формате КЛЮЧ=ЗНАЧЕНИЕ.

Подключение dotenv в Nuxt 2

В Nuxt 2 переменные окружения из .env по умолчанию не подхватываются самим фреймворком. Для этого добавьте пакет dotenv:

npm install --save-dev @nuxtjs/dotenv

Дальше подключите его в nuxt.config.js:

export default {
  modules: [
    '@nuxtjs/dotenv'
  ]
}

Теперь все переменные из .env будут автоматически доступны через process.env.

Передача переменных в клиентский код Nuxt 2

Nuxt 2 требует явного "экспорта" переменных в клиентский код через объект env в nuxt.config.js:

export default {
  env: {
    apiUrl: process.env.API_URL, // теперь доступно через process.env.apiUrl на клиенте
    debugMode: process.env.DEBUG_MODE
  }
}

Теперь внутри вашего приложения переменную можно получить так:

// Пример использования внутри компонента
mounted() {
  console.log(process.env.apiUrl); // https://api.example.com
}

Важно! Переменные окружения, которые вы не добавили через объект env, не будут доступны на клиенте.

Использование переменных окружения в Nuxt 3

В Nuxt 3 работа с переменными окружения стала проще благодаря встроенной поддержке Nuxt Nitro. Вам достаточно просто добавить файл .env в корень приложения. Для доступа разделяются два типа переменных:

Runtime Config (nuxt.config.ts)

Теперь все переменные удобнее структурировать с помощью runtimeConfig. Объявите в файле nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // Доступна только на сервере, не видна на клиенте
    public: {
      apiBase: '' // Доступна везде (клиент + сервер)
    }
  }
})

Дальше Nuxt автоматически подставит значения из переменных окружения, если вы назовете их в формате NUXTPUBLIC для public (например, NUXT_PUBLIC_API_BASE) и без префикса для приватных (например, API_SECRET).

Пример .env для Nuxt 3

NUXT_PUBLIC_API_BASE=https://api.example.com
API_SECRET=superSecretValue

Получение переменных в коде Nuxt 3

В любом серверном или клиентском файле используйте хук:

const config = useRuntimeConfig();
console.log(config.public.apiBase); // https://api.example.com
console.log(config.apiSecret); // Только на сервере!

На заметку: Значение apiSecret попадет только в серверный код. Это защищает секретные данные от утечек.

Передача переменных через командную строку

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

API_URL=https://api.example.com npm run dev

Либо для Windows:

set API_URL=https://api.example.com && npm run dev

Nuxt при старте подтянет эти значения.

Правильное использование переменных окружения — это критически важный навык для любого Nuxt-разработчика. Без него сложно представить себе разработку, тестирование и деплой современных приложений. Переменные окружения позволяют настраивать приложение под различные среды, не меняя код. Если вы хотите детальнее погрузиться в мир Nuxt, освоить все его тонкости и стать настоящим профессионалом — приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Использование переменных окружения в разных частях приложения

Доступ внутри компонентов

В Nuxt 2 записывайте значения через глобальный process.env.<имя>:

export default {
  mounted() {
    const debugMode = process.env.debugMode === 'true'; // из env: { debugMode } в nuxt.config.js
    if (debugMode) {
      console.log('Debug mode is on');
    }
  }
}

В Nuxt 3 лучше извлекать через хук:

const config = useRuntimeConfig();
const apiBase = config.public.apiBase;

Использование в серверных запросах

Пример для fetch-запроса с переменной окружения (Nuxt 3):

const config = useRuntimeConfig();
// Делаем API-запрос с использованием apiBase
const response = await $fetch(`${config.public.apiBase}/users`);

Использование в плагинах

Создайте плагин и используйте переменные окружения так же:

export default defineNuxtPlugin((nuxtApp) => {
  const apiUrl = useRuntimeConfig().public.apiBase;
  // теперь этот apiUrl можно прокинуть дальше в приложение
});

Использование в middleware

Здесь доступ аналогичен другим разделам:

export default defineNuxtRouteMiddleware((to, from) => {
  const config = useRuntimeConfig();
  // Например, можно проверить токен доступа
  if (!config.apiSecret) {
    throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
  }
});

Организация переменных окружения для разных сред

Использование отдельных файлов для сред

Популярная практика — создавать разные .env файлы:

• .env (по умолчанию)
• .env.development
• .env.production
• .env.staging

Nuxt (начиная с Nuxt 3) автоматически подхватит соответствующий файл, если вы запустите приложение с NODE_ENV=production:

NODE_ENV=production npm run build

Для Nuxt 2 с модулем @nuxtjs/dotenv можно явно указать конфиг:

export default {
  modules: [
    ['@nuxtjs/dotenv', { filename: '.env.production' }]
  ]
}

Переменные окружения в CI/CD

Часто CI-процессы передают секретные переменные окружения прямо в процессе сборки/деплоймента. Добавьте чувствительные значения в настройки CI/CD (через интерфейс GitLab, GitHub Actions или другого сервиса):

# .gitlab-ci.yml (пример)
variables:
  API_SECRET: $API_SECRET
  NUXT_PUBLIC_API_BASE: $NUXT_PUBLIC_API_BASE

Безопасность и best practices

Никогда не храните приватные ключи в public-config

Любое, что находится в public разделе runtimeConfig (или префиксе public/NUXT_PUBLIC_), будет собрано во frontend и станет видимым в js-коде пользователя. Не добавляйте туда секретные токены для доступа к сторонним API или базам данных.

Не коммитьте .env в общий репозиторий

Обычно добавляют файл .env в .gitignore:

# .gitignore
.env*

Вместо этого добавьте в репозиторий файл .env.example, где перечислены ключи без значений:

API_URL=
API_KEY=
DEBUG_MODE=

Это поможет команде понять, какие переменные нужны для запуска проекта.

Типичные ошибки при работе с переменными окружения

Проблема видимости

• Серверные переменные нельзя читать с клиента — используйте public-параметры, когда хотите значение на клиенте.

Перезапуск приложения

• После изменения файла .env нужно перезапустить dev-сервер — Nuxt не читает переменные динамически на лету.

Неправильный синтаксис .env

• Не используйте пробелы вокруг =
• Не используйте кавычки, если переменная строковая (либо учитывайте их как часть значения)
• Для логических значений всегда используйте строки "true"/"false" и приводите к нужному типу явно

Кэширование переменных

• При повторных билдах в docker, cd/cd часто используется закэшированный .env — убедитесь в актуальности переменных

Рефакторинг и структуризация: работа с большим количеством переменных

Если у вашего проекта десятки переменных, вы можете:

• Использовать неймспейсы (например, NUXTPUBLIC_APP, NUXTPUBLIC_API)
• Добавить проверку обязательных переменных (через модуль @nuxtjs/dotenv/check или самописную функцию)
• Оформить документацию для коллег с пояснением значения каждой переменной

Примеры удобных неймспейсов:

NUXT_PUBLIC_API_URL
NUXT_PUBLIC_API_VERSION
NUXT_PUBLIC_CDN_URL

В конфиге:

runtimeConfig: {
  public: {
    apiUrl: '',
    apiVersion: '',
    cdnUrl: ''
  }
}

Распространенные сценарии использования

Подключение к разным API в разных средах

Обычно создают переменные:

# .env.production
NUXT_PUBLIC_API_BASE=https://api.prod.com

# .env.development
NUXT_PUBLIC_API_BASE=http://localhost:3000

В application fetch:

// Экземпляр fetch всегда использует актуальный URL
await $fetch(`${useRuntimeConfig().public.apiBase}/data`)

Защищенный доступ к приватным ключам на сервере

# .env
API_SECRET=secret_token

В серверном middleware:

const { apiSecret } = useRuntimeConfig();
// apiSecret не попадет на клиент, доступен только в serverMiddleware

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

Если вы хотите менять переменные без пересборки, в production используйте переменные окружения через команду запуска (например, docker ENV или ручной экспорт).

Заключение

Работа с переменными окружения в Nuxt значительно облегчает процесс конфигурирования приложения и обеспечивает его гибкость, безопасность и переносимость. Nuxt предоставляет разные подходы для Nuxt 2 и Nuxt 3, позволяя реализовать как простые, так и сложные сценарии с разными уровнями доступа к данным. Важно помнить о разграничении публичных и приватных переменных, следить за безопасностью и придерживаться best practices по организации конфигов. Обратите внимание на специфику передачи данных между клиентом и сервером, а также на необходимость перезапускать приложение после смены переменных.

Умение работать с переменными окружения — это лишь один из аспектов разработки Nuxt-приложений. Чтобы стать настоящим профессионалом, необходимо освоить множество других навыков, таких как роутинг, работа с данными, стилизация и деплой. На курсе Nuxt - fullstack Vue фреймворк вы получите все необходимые знания и практические навыки для разработки современных веб-приложений на Nuxt. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в мир Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как динамически менять переменные окружения в runtime без билда?

В Nuxt переменные окружения "подхватываются" только при старте приложения (во время сборки и запуска dev/prod-серверов). Их нельзя менять на лету через reload страницы. Для смены нужно либо перезапускать сервер, либо использовать сторонний сервер (reverse proxy), который подставляет переменные, либо доделывать runtime-файлы конфигурации, что может быть нестабильно.

Почему переменная из .env не появляется в process.env?

Проверьте, что вы ее явно добавили в env секцию (Nuxt 2) или в runtimeConfig (Nuxt 3), что файл .env расположен в корне, и нет опечаток в ключе. Если вы меняли файл .env, обязательно перезапустите сервер.

Как использовать переменные окружения внутри composables (Nuxt 3)?

Комposables — обычные функции, и в них можно использовать useRuntimeConfig, как и в компонентах:

export function useApiUrl() {
  const config = useRuntimeConfig()
  return config.public.apiBase
}

Можно ли использовать переменные окружения в шаблонах (template)?

В template вы не можете напрямую получить process.env. Вместо этого пропишите необходимые значения в data или computed свойства на этапе рендера компонента, и выводите их уже через переменные:

export default {
  computed: {
    apiUrl() {
      return useRuntimeConfig().public.apiBase
    }
  }
}

Какое ограничение на размер и количество переменных окружения?

Практических ограничений в Nuxt нет, но крайне не рекомендуется передавать большие значения или сложные объекты — используйте строки и отделяйте конфиги, чтобы не перегружать публичный runtime config и не увеличивать размер клиентского bundle.