Деплой Next.js: Vercel, Self-Hosting и Docker

Зачем это нужно#

Разработка высокопроизводительного Next.js приложения требует четкого понимания его архитектуры развертывания в продакшене. Современный Next.js App Router — это не просто библиотека рендеринга, а сложный распределенный программный комплекс, объединяющий статический файловый сервер, Node.js-рантайм для потокового рендеринга (Streaming SSR), сервис оптимизации изображений и бессерверные обработчики Server Actions и Route Handlers.

Классический подход с запуском единственного долгоживущего процесса Node.js (pnpm run start) на виртуальном сервере (VPS) часто оказывается узким местом при резких всплесках нагрузки и требует ручной настройки балансировки трафика.

Платформа Vercel предлагает автоматическую декомпозицию приложения на статический CDN-слой, Serverless Functions и легковесные Edge Runtime воркеры. Однако в Enterprise-сегменте строгие требования безопасности, защита персональных данных и корпоративная инфраструктура требуют развертывания в изолированных кластерах Kubernetes. Понимание Standalone Mode и оптимизации Docker-образов необходимо для построения отказоустойчивых CI/CD пайплайнов.

Ментальная модель#

В процессе выполнения команды next build компилятор проводит комплексный статический анализ дерева маршрутов:

1. SSG / Prerendered Routes: Страницы без динамических функций (cookies(), headers(), некэшированных запросов) компилируются в статический HTML и отдаются напрямую из кэша с нулевой нагрузкой на CPU.
2. Dynamic / Streaming Routes: Страницы упаковываются в серверные чанки для выполнения в рантайме.

Разделение при деплое на Vercel#

Платформа автоматически распределяет артефакты сборки по специализированным слоям инфраструктуры:

• Статические ассеты (.next/static, шрифты, изображения) загружаются в глобальную сеть Edge CDN.
• Серверные компоненты и API-роуты упаковываются в независимые Serverless Functions (AWS Lambda).
• Промежуточное ПО (middleware.ts) исполняется на периферийных узлах Edge Network с минимальной сетевой задержкой.

Архитектура Self-Hosting (Docker / Kubernetes)#

При самостоятельном хостинге вы управляете долгоживущими контейнерами. Чтобы исключить попадание сотен мегабайт ненужных dev-зависимостей в продакшен-образ, Next.js задействует анализатор Node File Trace (NFT). Он собирает компактную директорию .next/standalone, содержащую только используемые модули и встроенный веб-сервер server.js.

Синтаксис и API#

Включение Standalone режима в next.config.ts#

Для создания легковесного production-сервера активируйте флаг output: 'standalone':

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Активирует генерацию минимального изолированного сервера в .next/standalone
  output: 'standalone',

  // Опционально: настройка внешнего Cache Handler для Kubernetes (Redis)
  // cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
};

export default nextConfig;

Эталонный Multi-stage Dockerfile с поддержкой pnpm#

Ниже приведен production-ready многоэтапный Dockerfile, соответствующий стандартам контейнеризации 2026 года:

# 1. Базовый образ с включением Corepack и pnpm
FROM node:22-alpine AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable

# 2. Установка зависимостей (кэшируемый слой)
FROM base AS deps
WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 3. Сборка приложения
FROM base AS builder
WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Отключение телеметрии на этапе сборки
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production

RUN pnpm run build

# 4. Продакшен-образ минимального размера (Runner)
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000
# Критично: привязка ко всем интерфейсам контейнера
ENV HOSTNAME="0.0.0.0"
ENV NEXT_TELEMETRY_DISABLED=1

# Безопасность: запуск от непривилегированного пользователя
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Копируем статические ассеты и скомпилированный standalone-сервер
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

# Запуск чистого Node.js микросервера без вызова тяжелого CLI Next.js
CMD ["node", "server.js"]

Практические паттерны#

1. Разделение переменных окружения (Build Time vs Runtime)#

В архитектуре Next.js переменные окружения строго разграничены по фазам жизненного цикла:

1. Переменные клиентской части (NEXT_PUBLIC_*): Встраиваются напрямую в JavaScript-бандл на этапе компиляции (next build). Их изменение в рантайме контейнера невозможно без пересборки.
2. Серверные секреты (DATABASE_URL, API_SECRET_KEY): Считываются динамически из process.env на сервере при каждом HTTP-запросе.

import 'server-only';
import { z } from 'zod';

const ServerEnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  AUTH_SECRET: z.string().min(32),
});

// Безопасный парсинг серверных переменных при старте контейнера
export const env = ServerEnvSchema.parse(process.env);

2. Распределенный кэш в Kubernetes через Cache Handler#

При горизонтальном масштабировании (HPA) в кластере Kubernetes запускаются десятки подов приложения. Локальный файловый кэш .next/cache на каждом поде изолирован, что приводит к рассинхронизации страниц при вызове revalidateTag(). Решение — вынос кэша в Redis через кастомный CacheHandler.

const { IncrementalCache } = require('@neshca/cache-handler');
const createRedisHandler = require('@neshca/cache-handler/redis-strings').default;
const { createClient } = require('redis');

IncrementalCache.onCreation(async () => {
  const client = createClient({ url: process.env.REDIS_URL });
  await client.connect();

  const redisHandler = await createRedisHandler({ client });

  return {
    cacheHandlers: [redisHandler],
  };
});

module.exports = IncrementalCache;

Распространённые ошибки#

Вопросы для собеседования#