re:re:actable
Урок 026 минут чтения

Как упаковать React-приложение на Vite в Docker

На этой странице

React SPA на Vite в production — это статические файлы. Docker-образ собирают в два stage: Node.js выполняет npm run build, Nginx раздаёт содержимое dist. Для React Router в режиме createBrowserRouter() или BrowserRouter нужен fallback на index.html (try_files), для ассетов с хэшем в имени — долгий кэш. Переменные VITE_* вшиваются в бандл при сборке и видны любому пользователю — секретов там быть не может. Для смены API-адреса без пересборки нужна runtime-конфигурация.

Production Dockerfile

# syntax=docker/dockerfile:1
FROM node:24-alpine AS build
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
 
COPY . .
 
ARG VITE_API_URL=/api
ENV VITE_API_URL=${VITE_API_URL}
 
RUN npm run build
 
FROM nginx:1.29-alpine
 
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
 
EXPOSE 80

CMD указывать не нужно: базовый образ Nginx уже запускает nginx -g "daemon off;".

В отличие от Vue, React обычно не требует отдельного шага проверки типов, если используется JavaScript. Если проект написан на TypeScript, проверку типов лучше выполнять отдельно в CI:

npx tsc --noEmit

При необходимости её можно включить непосредственно в сборку:

RUN npm run build

Например, в TypeScript-проекте можно настроить скрипт build так, чтобы он сначала проверял типы, а затем запускал Vite.

nginx.conf для SPA

server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;
 
  # Хэшированные ассеты можно кэшировать надолго
  location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
 
  # index.html не кэшировать
  location = /index.html {
    add_header Cache-Control "no-cache";
  }
 
  # React Router (BrowserRouter / createBrowserRouter)
  location / {
    try_files $uri $uri/ /index.html;
  }
 
  gzip on;
  gzip_types
    text/css
    application/javascript
    application/json
    image/svg+xml;
}

Без try_files прямой переход или обновление страницы /profile/42 вернёт 404, поскольку Nginx будет искать физический файл или директорию.

Если используется React Router с BrowserRouter:

import { BrowserRouter, Routes, Route } from "react-router-dom";
 
function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/profile/:id" element={<Profile />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </BrowserRouter>
  );
}

Fallback Nginx позволяет React Router самостоятельно обработать URL и показать нужную страницу.

Если используется HashRouter, URL выглядят как /#/profile/42. В этом случае fallback для маршрутизации не нужен, поскольку браузер не отправляет часть URL после # серверу.

Если приложение отдаётся не из корня, например /app/, нужно указать базовый путь в vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
  plugins: [react()],
  base: "/app/",
});

А в React Router использовать соответствующий basename:

<BrowserRouter basename="/app">
  <App />
</BrowserRouter>

Также потребуется соответствующая настройка Nginx.

Проксирование API

Чтобы не настраивать CORS, Nginx может проксировать запросы на backend в той же Docker-сети:

location /api/ {
  proxy_pass http://api:3000/;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

В React обращаемся к относительному адресу /api:

const response = await fetch("/api/users");
const users = await response.json();

Таким образом, один Docker-образ можно использовать в разных окружениях без изменения API-адреса.

Переменные окружения: build-time и runtime

В Vite переменные окружения с префиксом VITE_ доступны через import.meta.env.

Например:

const apiUrl = import.meta.env.VITE_API_URL;

Значение import.meta.env.VITE_API_URL заменяется строкой непосредственно во время vite build.

Поэтому изменить его через docker run -e после сборки нельзя.

Есть три основных варианта.

  1. Собирать отдельный образ для каждого окружения
docker build \
  --build-arg VITE_API_URL=https://api.example.com \
  -t react-app .

Просто, но нарушает принцип «собрать один раз — запустить где угодно».

  1. Использовать относительные адреса и Nginx Proxy
fetch("/api/users");

Это обычно лучший вариант: API доступен через тот же домен, а Nginx перенаправляет запросы на backend.

  1. Генерировать config.js при запуске контейнера

Если API-адрес должен меняться без пересборки образа, можно использовать runtime-конфигурацию.

Создаём скрипт /docker-entrypoint.d/40-config.sh:

#!/bin/sh
 
cat > /usr/share/nginx/html/config.js <<EOF
window.__CONFIG__ = {
  apiUrl: "${API_URL}"
};
EOF

Официальный образ Nginx выполняет скрипты из /docker-entrypoint.d/ перед запуском сервера.

В index.html подключаем конфигурацию до скрипта приложения:

<script src="/config.js"></script>

Создаём src/config.ts:

declare global {
  interface Window {
    __CONFIG__?: {
      apiUrl: string;
    };
  }
}
 
export const config = {
  apiUrl:
    window.__CONFIG__?.apiUrl ??
    import.meta.env.VITE_API_URL ??
    "/api",
};

Теперь в React можно использовать:

import { config } from "./config";
 
fetch(`${config.apiUrl}/users`);

При запуске контейнера передаём переменную:

docker run \
  -p 8080:80 \
  -e API_URL=https://api.example.com \
  react-app

Важно: runtime-конфигурация также публична. Не храните в ней токены, пароли и другие секреты.

Разработка

Для разработки не нужен Nginx. Достаточно Node.js и Vite Dev Server с горячей перезагрузкой (HMR).

Создаём compose.yaml:

services:
  web:
    image: node:24-alpine
    working_dir: /app
    command: sh -c "npm ci && npm run dev -- --host 0.0.0.0"
    ports:
      - "5173:5173"
    volumes:
      - .:/app
      - /app/node_modules

Запускаем:

docker compose up

Приложение будет доступно по адресу:

http://localhost:5173

--host 0.0.0.0 нужен, чтобы Vite принимал подключения извне контейнера.

То же самое можно указать в vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
  plugins: [react()],
  server: {
    host: true,
  },
});

Если HMR не работает на macOS или Windows, попробуйте включить polling:

server: {
  host: true,
  watch: {
    usePolling: true,
  },
},

Если страница открыта через другой порт или прокси, WebSocket HMR можно настроить через server.hmr.clientPort.

.dockerignore

Чтобы не копировать лишние файлы в Docker build context, добавляем .dockerignore:

node_modules
dist
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile*
compose.yaml
npm-debug.log*

Это ускоряет сборку и уменьшает размер контекста. При этом .env не должен содержать секреты, которые случайно попадут в образ.

Частые ошибки

  • Запускать vite dev или vite preview в production вместо Nginx.

  • Забыть SPA fallback для React Router с BrowserRouter.

  • Положить секрет в VITE_*.

  • Ожидать, что docker run -e VITE_API_URL изменит уже собранный бандл.

  • Кэшировать index.html надолго — пользователи могут продолжать получать старую версию приложения.

  • Не добавить .dockerignore и копировать node_modules с хостовой машины.

  • Не использовать npm ci для воспроизводимой установки зависимостей.

  • Забыть --host 0.0.0.0 при запуске Vite внутри контейнера.

Что важно помнить

  • Node.js нужен только на этапе сборки. В production работает исключительно Nginx.

  • Финальный Docker-образ получается небольшим — без Node.js и node_modules.

  • React Router с BrowserRouter требует SPA fallback на index.html.

  • Всё, что попало в клиентский бандл, публично.

  • Один образ для всех окружений достигается использованием относительных API-адресов или runtime-конфигурации.

  • Для разработки достаточно Node.js, Docker Compose и Vite Dev Server.

Мини-шпаргалка

ЗадачаРешение
ProductionNode.js build → Nginx
DevVite Dev Server
React Routertry_files $uri $uri/ /index.html
Хэшированные ассетыCache-Control: immutable
index.htmlCache-Control: no-cache
APIОтносительный /api + Nginx proxy
Переменные Viteimport.meta.env.VITE_*
Runtime configwindow.__CONFIG__
Docker Compose Dev--host 0.0.0.0

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам