Learn Nuxt with a Collection of 100+ Tips!

Runtime-конфиг

Nuxt предоставляет API рантайм-конфигурации для доступа к конфигу и секретам в вашем приложении.

Раскрытие

Чтобы передать конфигурацию и переменные окружения остальным частям вашего приложения, вам нужно определить конфигурацию времени выполнения в файле nuxt.config, используя опцию runtimeConfig.

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Приватные ключи, которые доступны только на стороне сервера
    apiSecret: '123',
    // Ключи, находящиеся в public, также будут открыты на стороне клиента
    public: {
      apiBase: '/api'
    }
  }
})

При добавлении apiBase в runtimeConfig.public, Nuxt добавляет его в полезную нагрузку каждой страницы. Мы можем универсально обращаться к apiBase как на сервере, так и в браузере.

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
Публичный конфиг времени выполнения доступен в шаблонах Vue с помощью $config.public.

Сериализация

Ваша конфигурация времени выполнения будет сериализована перед передачей в Nitro. Это означает, что все, что не может быть сериализовано и затем десериализовано (например, функции, Set, Map и так далее), не должно быть установлено в вашем nuxt.config.

Вместо того чтобы передавать несериализуемые объекты или функции в ваше приложение из вашего nuxt.config, вы можете поместить этот код в плагин или в middleware Nuxt или Nitro.

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

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

В Nuxi CLI встроена поддержка чтения файла .env при разработке, сборке и генерации. Но когда вы запускаете собранный сервер, ваш файл .env не будет прочитан.
Узнать больше Docs > Guide > Directory Structure > Env.

Значения конфигурации времени выполнения автоматически заменяются соответствующими переменными окружения во время выполнения.

Существует два ключевых требования:

  1. Желаемые переменные должны быть определены в файле nuxt.config. Это гарантирует, что произвольные переменные окружения не попадут в код вашего приложения.
  2. Только переменная окружения со специальным именем может переопределить свойство конфигурации времени выполнения. То есть, переменная окружения, начинающаяся с NUXT_ и использующая _ для разделения ключей и изменения регистра.
Установка по умолчанию значений runtimeConfig в различные по названию переменные окружения (например, установка myVar в process.env.OTHER_VARIABLE) будет работать только во время сборки и приведет к поломке во время выполнения. Рекомендуется использовать переменные окружения, соответствующие структуре вашего объекта runtimeConfig.
Посмотрите видео от Александра Лихтера, демонстрирующее основные ошибки разработчиков при использовании runtimeConfig.

Пример

.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // может быть переопределена переменной окружения NUXT_API_SECRET
    public: {
      apiBase: '', // может быть переопределена переменной окружения NUXT_PUBLIC_API_BASE
    }
  },
})

Чтение

Приложение Vue

Во Vue-части вашего приложения Nuxt вам нужно вызвать useRuntimeConfig(), чтобы получить доступ к конфигурации времени выполнения.

Поведение объекта отличается на клиенте и на сервере:
  • На клиенте доступны только ключи в runtimeConfig.public, а сам объект доступен для записи и реактивен.
  • На сервере весь runtime-конфиг доступен, но он доступен только для чтения, чтобы избежать разделения контекста.
pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('Runtime-конфиг:', config)
if (import.meta.server) {
  console.log('API секрет:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>Проверьте консоль разработчика!</div>
  </div>
</template>
Примечание по безопасности: Будьте осторожны и не раскрывайте ключи конфигурации времени выполнения на клиенте, отображая их или передавая в useState.

Плагины

Если вы хотите использовать конфигурацию времени выполнения внутри любого (пользовательского) плагина, вы можете использовать useRuntimeConfig() внутри вашей функции defineNuxtPlugin.

plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('Базовый URL API:', config.public.apiBase)
});

Серверные маршруты

Вы можете получить доступ к конфигурации времени выполнения и внутри маршрутов сервера, используя useRuntimeConfig.

server/api/test.ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`
    }
  })
  return result
})
Передача event в качестве аргумента useRuntimeConfig необязательна, но рекомендуется передавать его, чтобы во время выполнения серверных маршрутов конфигурация времени выполнения была перезаписана переменными окружения.

Типизация runtime-конфига

Nuxt пытается автоматически сгенерировать интерфейс typescript из предоставленного конфига времени выполнения, используя unjs/untyped.

Но можно также набрать свой конфиг вручную:

index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// Всегда важно убедиться, что вы импортируете/экспортируете что-то при дополнении типа
export {}
nuxt/schema предоставляется для удобства конечных пользователей, чтобы получить доступ к версии схемы, используемой Nuxt в их проекте. Авторы модулей должны вместо этого дополнять @nuxt/schema.