Как упаковать 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 80CMD указывать не нужно: базовый образ 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 после сборки нельзя.
Есть три основных варианта.
- Собирать отдельный образ для каждого окружения
docker build \
--build-arg VITE_API_URL=https://api.example.com \
-t react-app .Просто, но нарушает принцип «собрать один раз — запустить где угодно».
- Использовать относительные адреса и Nginx Proxy
fetch("/api/users");Это обычно лучший вариант: API доступен через тот же домен, а Nginx перенаправляет запросы на backend.
- Генерировать 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.
Мини-шпаргалка
| Задача | Решение |
|---|---|
| Production | Node.js build → Nginx |
| Dev | Vite Dev Server |
| React Router | try_files $uri $uri/ /index.html |
| Хэшированные ассеты | Cache-Control: immutable |
index.html | Cache-Control: no-cache |
| API | Относительный /api + Nginx proxy |
| Переменные Vite | import.meta.env.VITE_* |
| Runtime config | window.__CONFIG__ |
| Docker Compose Dev | --host 0.0.0.0 |