Как настроить config в Nuxt

Главная

База знаний

nuxt

Основы Nuxt

04 сентября 2025

Автор

Олег Марков

Введение

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

В этой статье я расскажу вам, как устроена настройка config в Nuxt разных версий (актуальная третья и предыдущая вторая), какие возможности вам дает этот файл, подробно объясню структуру конфигов и разберём ряд практических примеров. Вы узнаете, как управлять плагинами, подключать модули, работать с переменными среды, изменять роутер, кастомизировать сборку, а также рассмотрим лучшие практики для минимизации ошибок в будущем.

Где находится и как называется config-файл Nuxt

По умолчанию основной конфиг-файл в Nuxt называется nuxt.config.js и располагается в корне проекта. В зависимости от требований он может иметь расширение .ts (если вы пишете на TypeScript).

Nuxt 2: nuxt.config.js
Nuxt 3: nuxt.config.js или nuxt.config.ts

Когда Nuxt запускает приложение, он автоматически ищет этот файл и использует все настройки, которые вы туда внесли.

Структура nuxt.config в разных версиях

Nuxt 2

В Nuxt 2 конфиг — это обычный JS-объект, который экспортируется через module.exports:

// nuxt.config.js (Nuxt 2)
module.exports = {
  // Здесь описываются все параметры конфигурации Nuxt 2
  target: 'server', // или 'static'
  head: {
    title: 'My Nuxt App',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' }
    ]
  },
  modules: ['@nuxtjs/axios'],
  plugins: [],
  env: {},
  build: {},
  // и другие параметры
}

Nuxt 3

В Nuxt 3 используется современный синтаксис экспорта — экспорт по умолчанию обычного объекта или функции:

// nuxt.config.js (Nuxt 3)
export default defineNuxtConfig({
  // Конфигурационные опции Nuxt 3
  app: {
    head: {
      title: 'My Nuxt 3 App'
    }
  },
  modules: ['@nuxtjs/tailwindcss'],
  runtimeConfig: {
    public: { apiBase: '/api' },
    // приватные переменные — доступны только на сервере
    secretKey: ''
  },
  // и другие параметры
})

defineNuxtConfig — это хелпер, который даёт дополнительные подсказки типов и работает корректно с TypeScript.

Основные разделы nuxt.config

Разобраться в структуре стоит на примерах ключевых параметров, которые чаще всего используются в реальных проектах.

Глобальные параметры (`head`/`app.head`)

Этот раздел конфигурации позволяет управлять HTML <head> вашего приложения: заголовком страницы, мета-тегами, favicon и т.д.

Пример для Nuxt 3

// nuxt.config.js
export default defineNuxtConfig({
  app: {
    head: {
      title: 'Nuxt App',
      meta: [
        { name: 'description', content: 'Описание моего приложения на Nuxt' }
      ],
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }
      ]
    }
  }
})
// Здесь вы определяете заголовок страницы и базовые мета-теги

Пример для Nuxt 2

module.exports = {
  head: {
    title: 'Nuxt 2 App',
    meta: [ { name: 'description', content: 'Описание Nuxt 2 приложения' } ],
    link: [ { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' } ]
  }
}
// Структура похожа, но секция называется head, а не app.head

Работа с переменными среды

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

Nuxt 2: секция `env`

module.exports = {
  env: {
    apiBaseUrl: process.env.API_BASE_URL || 'https://api.example.com'
  }
}
// Теперь везде в вашем коде process.env.apiBaseUrl будет передано внутрь приложения

Nuxt 3: секция `runtimeConfig`

В Nuxt 3 это реализовано более прозрачно и гибко:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.API_BASE_URL || 'https://api.example.com'
    },
    // приватное значение для серверного использования
    secretKey: process.env.SECRET_KEY
  }
})
// Для получения значения в коде используйте useRuntimeConfig()

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

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

// Внутри composable или любого сервиса
const config = useRuntimeConfig()
console.log(config.public.apiBase) // доступно и на клиенте, и на сервере

Подключение модулей

Nuxt позволяет расширять функционал через модули. Вы подключаете их в секции modules.

Пример

// Добавим Tailwind CSS и Axios
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/axios', // Nuxt 2
    '@nuxtjs/tailwindcss' // Актуально для Nuxt 3
  ]
})
// Модули автоматически подхватят свои настройки, некоторые модули требуют дополнительной кастомизации

Подключение и настройка плагинов

Подключать собственные или сторонние плагины удобно через секцию plugins.

Пример (Nuxt 2)

module.exports = {
  plugins: [
    '~/plugins/my-plugin.js'
  ]
}
// Путь указывается относительно корня проекта

Пример (Nuxt 3)

В Nuxt 3 плагины обнаруживаются автоматически, если размещают в папке /plugins, однако вы можете использовать ручную регистрацию через секцию plugins.

Кастомизация роутера

Если требуется особая логика роутинга, например, добавление middleware или изменение поведения маршрутов, это тоже может быть описано в config-файле.

Nuxt 2: секция `router`

module.exports = {
  router: {
    middleware: ['auth'], // глобальное подключение middleware
    extendRoutes(routes, resolve) {
      routes.push({
        name: 'custom',
        path: '/custom-route',
        component: resolve(__dirname, 'pages/custom.vue')
      })
    }
  }
}

Nuxt 3

В версии 3 базовая настройка роутера происходит декларативно через структуру папки /pages. Более сложные настройки делаются через плагины или Nitro hooks.

Сборка и оптимизация (`build`/`vite`)

Тонкая настройка процесса сборки:

Nuxt 2: `build`

module.exports = {
  build: {
    extend(config, { isDev, isClient }) {
      // Здесь вы можете изменить webpack-конфиг Nuxt
      if (isDev && isClient) {
        config.devtool = 'source-map'
      }
    }
  }
}

Nuxt 3: через `vite` и другие опции

export default defineNuxtConfig({
  vite: {
    server: {
      port: 3002
    }
  }
})
// Для изменений используйте те же параметры, что в обычном Vite-проекте

Работа с TypeScript

Если вы пишете на TypeScript, просто используйте расширение .ts для config-файла:

nuxt.config.ts

В случае Nuxt 3 это полностью поддерживается из коробки.

Пример:

// nuxt.config.ts
export default defineNuxtConfig({
  // ваши опции здесь
})
// TypeScript подхватит типы автоматически после установки @nuxt/types или @nuxt/typescript-build

Разделение настроек для разных сред

Часто настройки для разработки и продакшена разные. Обычно это делается через переменные окружения:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NODE_ENV === 'production'
        ? 'https://api.prod.com'
        : 'http://localhost:3000'
    }
  }
})

Расширенные возможности nuxt.config

Некоторые возможности позволяют еще сильнее кастомизировать приложение и его поведение.

Использование пользовательской логики в конфиге

Вы можете экспортировать функцию, которая возвращает объект конфигурации. Это позволяет вычислять параметры на лету.

export default () => {
  const isProd = process.env.NODE_ENV === 'production'
  return defineNuxtConfig({
    app: { head: { title: isProd ? 'Prod App' : 'Dev App' } }
  })
}

Глобальные CSS и скрипты

Nuxt 2: через секцию `css`

module.exports = {
  css: [
    '@/assets/main.css',
    'bulma/css/bulma.css'
  ]
}

Nuxt 3: через секцию `css` (без знака @)

export default defineNuxtConfig({
  css: [
    '~/assets/main.css',
    'bulma/css/bulma.css'
  ]
})

Локализация (i18n) через config

Для мультиязычных проектов обычно используется модуль i18n:

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: ['en', 'ru'],
    defaultLocale: 'en',
    vueI18n: {
      fallbackLocale: 'en',
      messages: {
        en: { welcome: 'Hello' },
        ru: { welcome: 'Привет' }
      }
    }
  }
})

Aliases и оптимизация путей

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

export default defineNuxtConfig({
  alias: {
    '@components': '/src/components'
  }
})

Теперь в коде можно писать:

import MyButton from '@components/MyButton.vue'

Практические советы и частые ошибки

Сохраняйте консистентность: Не смешивайте Nuxt 2 и Nuxt 3 опции, если проект явно не требует мультиверсионной поддержки.
Используйте dotenv: Для разных окружений удобно хранить .env файлы и подгружать их значения.
Следите за версионированием модулей: Nuxt 3 поддерживает только те модули, которые были адаптированы для него — всегда проверяйте совместимость.
Минимизируйте логику в nuxt.config: Конфиг должен быть читаемым и простым, не вносите избыточную пользовательскую логику.
Настройте автоимпорт: Nuxt 3 поддерживает автоимпорт composable и компонентов — используйте для ускорения разработки.
Не забывайте про lint: Если работаете на TypeScript, настройте linters и types для поддержки конфигов из коробки.

Заключение

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

Ваша задача — не только быстро настроить проект, но и поддерживать прозрачность и гибкость этих настроек на протяжении всего жизненного цикла разработки. Используйте возможности nuxt.config на полную: создавайте удобные алиасы, разделяйте переменные среды, экспериментируйте с модулями и не забывайте о лаконичности и структуре.

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

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

Вопрос 1. Как подгрузить секретные переменные только на сервере и не отдавать их клиенту?

Ответ:
В Nuxt 3 помещайте такие переменные внутрь верхнего уровня объекта runtimeConfig, а не в runtimeConfig.public.
js export default defineNuxtConfig({ runtimeConfig: { secretKey: process.env.SECRET_KEY } })
Получайте их только на сервере через useRuntimeConfig().

Вопрос 2. Как добавить дополнительные статические директории для раздачи через Nuxt?

Ответ:
В Nuxt 3 используйте опцию dir.public или добавьте папки в server.assets внутри конфига. Можно просто положить файлы в папку /public — Nuxt отдаёт всё содержимое этой папки как статику.

Вопрос 3. Как подключить стороннюю библиотеку и сделать её глобально доступной во всем приложении?

Ответ:
Создайте плагин в папке /plugins, импортируйте библиотеку и зарегистрируйте её в Nuxt. Например, для lodash: js // plugins/lodash.js import _ from 'lodash' export default defineNuxtPlugin(() => { return { provide: { _: _ } } }) Теперь используйте через useNuxtApp().$_.map().

Вопрос 4. Как динамически менять config без перезапуска приложения?

Ответ:
Nuxt config считается на этапе сборки/старта. Чтобы динамически изменять параметры, загружайте переменные (например, базовый API url) из process.env, а при изменении переменной среды перезапускайте проект.

Вопрос 5. Можно ли использовать разные config для разных сайтов в монорепозитории?

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