Как запустить Nuxt-приложение в production

Введение

Nuxt.js — это популярный open source-фреймворк для разработки современных приложений на Vue.js. Он предназначен для создания серверно-рендеренных приложений (SSR), статических сайтов (SSG) и SPA. Но даже если вы уверенно разворачиваете проекты на локальной машине, запуск Nuxt-приложения в production может показаться непростым — тут и сборка, и вопрос хоста, и переменные окружения, и оптимизация.

В этой статье я помогу вам пройти весь путь от подготовки Nuxt-проекта к production, его сборки до публикации на сервере и настройки важнейших параметров. Здесь вы найдете примеры кода с пояснениями, практические советы по безопасности, оптимизации и автоматизации деплоя. Я постараюсь рассмотреть как общие концепции, так и нюансы, которые важны для реального продакшн-развертывания.

Выбор режима работы: SSR, SSG или SPA

Перед деплоем важно четко понимать, в каком режиме должен работать ваш Nuxt-проект:

• SSR (Server-Side Rendering): Рендеринг страниц на сервере, динамическая генерация (отлично для SEO и интерактивных веб-приложений).
• SSG (Static Site Generation): Сайт генерируется статически на этапе сборки (быстро, удобно для контентных сайтов).
• SPA (Single Page Application): Чистый frontend, подходящий для веб-приложений без SEO-требований.

Каждый режим задается в конфиге nuxt.config.js через параметр ssr:

// nuxt.config.js
export default {
  ssr: true, // true - SSR; false - SPA
  target: 'server' // 'server' (SSR), 'static' (SSG)
}

• Для SSR: ssr: true, target: 'server'
• Для SSG: ssr: true, target: 'static'
• Для SPA: ssr: false

Это влияет и на процесс сборки, и на специфику деплоя. Давайте разберёмся с подготовкой каждого режима.

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

Подготовка к production

Перед тем, как начинать сборку и деплой, убедитесь, что выполнили необходимые подготовительные шаги. Это сделает финальный запуск стабильным и безопасным.

Управление переменными окружения

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

Например, файл .env:

API_URL=https://api.example.com
GOOGLE_ANALYTICS_ID=UA-XXXXXX

Загрузите переменные с помощью библиотеки @nuxtjs/dotenv или через встроенную поддержку Nuxt:

// nuxt.config.js
export default {
  runtimeConfig: {
    public: {
      apiUrl: process.env.API_URL
    },
    private: {
      secret: process.env.SECRET_KEY
    }
  }
}

Чтобы переменные не попали случайно в client bundle, разделяйте public и private параметры.

Оптимизация настроек проекта

• Проверьте настройки кеширования и сжатия (например, nuxt-compression).
• Настройте работу с cookies, авторизацией и заголовками.
• Проверьте правильность конфигурации роутинга.
• Используйте webpack-bundle-analyzer для анализа размера бандла (nuxt build --analyze).

Сборка Nuxt-приложения

Давайте рассмотрим пошаговый процесс сборки проекта для разных модов.

Команды для сборки

• SSR (Nuxt 3 и Nuxt 4):

  # Сборка production-бандла — результат попадёт в папку .output
  npm run build
  
  # Запуск собранного приложения в production-режиме
  node .output/server/index.mjs
  

  Локально посмотреть, как ведёт себя production-сборка, можно через встроенный превью-сервер:

  # nuxt preview поднимает собранное приложение на локальной машине
  npm run preview
  

• SSR (Nuxt 2):

  # В Nuxt 2 за запуск production-сервера отвечает команда nuxt start
  npm run build
  npm run start
  

• SPA:

  npm run build
  npm run generate # для статической генерации
  

Подробный разбор команд

• npm run build — собирает приложение, оптимизируя скрипты, CSS, производит tree shaking. Для SSR и SSG выполняет подготовку серверной части. В Nuxt 3 и Nuxt 4 результат сборки складывается в папку .output.
• npm run generate — генерирует полностью статический сайт, если используется режим SSG.
• node .output/server/index.mjs — запускает production-сервер в Nuxt 3 и Nuxt 4. После этого приложение доступно на выбранном порте (по умолчанию 3000).
• npm run preview — поднимает собранное приложение локально для проверки перед деплоем. Это инструмент разработчика, для боевого сервера он не предназначен.
• npm run start — production-сервер в Nuxt 2. Обратите внимание: в Nuxt 3 и Nuxt 4 такого скрипта в стандартном шаблоне нет, и эта команда приложение не запустит.

Теперь давайте развернем приложение на сервере.

Размещение приложения на сервере

После сборки переходим к публикации Nuxt-приложения.

Выбор хостинга

Nuxt можно запускать на:

• VPS (например, DigitalOcean, Hetzner, Yandex.Cloud, AWS, GCP, Azure)
• Platform-as-a-Service (Vercel, Netlify, Heroku)
• Специализированные сервисы Nuxt (Layer0, Render)

Вам потребуется Node.js на сервере. Лучше ставить LTS-версию (например, 18 или 20).

Копирование файлов

Перенесите на сервер:

• всю папку проекта (или только необходимые файлы из сборки)
• файл package.json и package-lock.json
• файл .env (только не добавляйте его в публичные репозитории)
• вашу папку .output, .nuxt или папку dist — в зависимости от режима

Установка зависимостей

На сервере выполните:

npm ci # или npm install --production

Используйте npm ci для быстрой и точной установки зависимостей на CI/CD или production-сервере.

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

В Nuxt 3 и Nuxt 4 боевой сервер запускается напрямую из собранного бандла — отдельный npm-скрипт для этого не нужен.

# Nuxt 3 / Nuxt 4 — запуск production-сервера
node .output/server/index.mjs
# Стартует на порте 3000 по умолчанию

Порт и хост задаются переменными окружения:

PORT=8080 HOST=0.0.0.0 node .output/server/index.mjs

В Nuxt 2 для этой задачи используется npm run start.

Конфигурирование прокси и HTTPS

Для большей устойчивости и поддержки HTTPS на практике Nuxt часто запускается за обратным прокси — популярные варианты nginx или Caddy.

Пример конфигурации nginx

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000; # Nuxt-приложение работает на 3000 порту
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Добавьте SSL через Certbot/Let's Encrypt или другой способ, чтобы перейти на https.

Использование process manager (pm2)

Для управления процессом Nuxt на сервере удобно применять pm2:

npm install pm2 -g

# Запуск production-приложения Nuxt через pm2
pm2 start npm --name "nuxt-app" -- run start

# Рестарт, мониторинг и автостарт
pm2 restart nuxt-app
pm2 logs nuxt-app
pm2 save
pm2 startup

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

Деплой: CI/CD, автоматизация и обновления

Для актуализации кода используйте систему автоматизированного деплоя (например, Github Actions, Gitlab CI, Bitbucket Pipelines, Jenkins).

Общий пайплайн деплоя

1. Склонировать репозиторий: bash git clone ...
2. Установить зависимости: bash npm ci
3. Собрать проект: bash npm run build

4. Перезапустить приложение:

   pm2 restart nuxt-app
   

   Все эти шаги легко автоматизировать в CI/CD-пайплайнах через выполнение shell-скриптов и установку переменных окружения (API-ключи, домены).

Оптимизация безопасности

Для production имеете в виду:

• Следите, чтобы .env-файл не попал в публичный репозиторий.
• Отключите дебаг-режим и детализацию ошибок в production (dev: false).
• Проверьте конфиг CORS, если работаете с API.

Добавьте необходимые security-заголовки:

// пример Middleware (serverMiddleware в nuxt.config.js)
(req, res, next) => {
  res.setHeader('X-Frame-Options', 'DENY')
  res.setHeader('X-XSS-Protection', '1; mode=block')
  next()
}

Сжимайте ответы с помощью модулей @nuxtjs/compression или через настройку прокси.

Особенности статической генерации (SSG)

Если вы создаете статический сайт, сборка и деплой будут чуть отличаться.

Сборка SSG

npm run generate
# Создаст папку .output/public или dist

Содержимое папки dist можно закачивать на любой web-сервер или CDN без Node.js.

Деплой SSG

Выкладывайте содержимое на хостинги для статических файлов: Netlify, Vercel, Github Pages, Firebase Hosting, Cloudflare Pages и др.

• Просто перетащите содержимое папки dist: bash netlify deploy --dir=dist
• Для Github Pages: bash npx gh-pages -d dist

Работа с логированием и ошибками

Для production посетите раздел error-handling:

• Используйте сторонние сервисы (Sentry, Bugsnag) для автоматического логирования ошибок.
• Пишите серверные логи через pm2: bash pm2 logs nuxt-app
• Добавьте custom error-страницы через layouts/error.vue — пользователи будут видеть их вместо стандартных ошибок Nuxt.

Обновление приложения

Для выката новых версий:

1. Подтяните новые коммиты из репозитория.
2. Переустановите зависимости, если нужно.
3. Воспроизведите сборку (npm run build).
4. Перезапустите сервер (pm2 restart).

Рекомендуется предварительно тестировать обновления на staging-сервере или с помощью feature-флагов.

Заключение

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

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

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

Как поменять порт у production-приложения Nuxt?

В Nuxt 3 и Nuxt 4 порт задаётся переменной окружения при запуске собранного бандла:

PORT=4000 node .output/server/index.mjs

Переменную можно вынести и в .env. В Nuxt 2 для этого использовались PORT=4000 npm run start или опция nuxt start -p 4000. Если вы используете platform-as-a-service, иногда порт задаётся самой платформой (например, Heroku присваивает $PORT).

Как безопасно хранить .env-файлы и переменные окружения?

Переменные окружения не должны попадать в git-репозиторий, добавьте .env в .gitignore. Для production используйте секреты CI/CD или файловую систему сервера. Например, в Github Actions переменные можно хранить в секретах репозитория.

Можно ли использовать Nuxt-приложение в Docker-контейнере?

Да, создайте Dockerfile с установкой зависимостей, сборкой проекта и запуском сервера. Вот краткий пример:

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build
EXPOSE 3000
CMD ["npm", "run", "start"]

Оптимизируйте размер образа, добавив .dockerignore.

Как перенаправить трафик на Nuxt через nginx с поддержкой HTTPS?

Настройте reverse proxy в nginx, добавив SSL через Certbot. Минимальная настройка — описана выше, для HTTPS добавьте сертификаты:

listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

Перенаправляйте HTTP на HTTPS с помощью return 301.

Приложение долго стартует или сборка занимает много времени. Как ускорить?

Проверьте количество и вес npm-пакетов. Используйте [webpack-bundle-analyzer] для поиска крупных зависимостей, минимизируйте сторонние библиотеки. Обновите Node.js до свежей LTS-версии, отключите ненужные плагины и выберите production-режим сборки (NODE_ENV=production).