Как упаковать Node.js-приложение в Docker
На этой странице
Production-образ Node.js-приложения собирают multi-stage: в одном stage ставят все зависимости и компилируют TypeScript, в финальном — только production-зависимости и dist. Важные детали: lock-файл и npm ci до копирования кода (кэш), .dockerignore, запуск через node, а не npm start (сигналы), пользователь node вместо root, сервер слушает 0.0.0.0, логи идут в stdout, приложение корректно завершается по SIGTERM.
Вопрос
Как правильно упаковать Node.js-приложение (например, API на Express или NestJS) в Docker?
Production Dockerfile
# syntax=docker/dockerfile:1
FROM node:24-alpine AS base
WORKDIR /app
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
FROM deps AS build
COPY . .
RUN npm run build
FROM base AS prod-deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
FROM base AS runner
ENV NODE_ENV=production
COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --chown=node:node package.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"].dockerignore
node_modules
dist
coverage
.git
.env
.env.*
*.log
Dockerfile*
compose*.yamlЧто важно в коде приложения
const server = app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0");
process.on("SIGTERM", () => {
server.close(() => {
db.end().finally(() => process.exit(0));
});
});- Слушать
0.0.0.0, иначе опубликованный порт не будет работать. - Обрабатывать SIGTERM:
docker stopи любые оркестраторы останавливают контейнер именно им. - Конфигурацию читать из переменных окружения, а не из файла в образе.
- Логировать в stdout в формате JSON — их соберёт Docker или платформа.
Почему node, а не npm start
CMD ["npm", "start"] делает PID 1 процесс npm, а Node.js — его потомком. npm ненадёжно пересылает сигналы, поэтому приложение может не получить SIGTERM и будет убито через 10 секунд. Запускайте node напрямую или добавьте init: true (tini) — подробнее в уроке про PID 1.
Выбор базового образа
| Образ | Размер | Особенности |
|---|---|---|
node:24 | ~1 ГБ | Полный Debian — для сборки с компиляторами |
node:24-slim | ~250 МБ | Debian без лишнего, glibc — совместим с большинством native-модулей |
node:24-alpine | ~150 МБ | musl libc: некоторые native-модули (sharp, bcrypt, Prisma) требуют особых бинарников |
gcr.io/distroless/nodejs24-debian12 | ~130 МБ | Нет shell и пакетного менеджера — минимальная поверхность атаки, сложнее отладка |
Если с Alpine возникают ошибки загрузки native-модулей, первым делом пробуют -slim.
pnpm и монорепозиторий
FROM node:24-alpine AS base
RUN corepack enable
WORKDIR /app
FROM base AS build
COPY . .
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
pnpm install --frozen-lockfile
RUN pnpm --filter api build
RUN pnpm --filter api deploy --prod /out # изолированный пакет с prod-зависимостями
FROM node:24-alpine AS runner
WORKDIR /app
COPY --from=build /out .
USER node
CMD ["node", "dist/main.js"]pnpm deploy собирает каталог только с нужным пакетом и его зависимостями — без всего монорепозитория.
Частые ошибки
COPY . .доnpm ci— нет кэша.npm installвместоnpm ci— невоспроизводимые версии..envв образе.- Сервер на
localhostвнутри контейнера. - devDependencies и исходники в финальном образе.
- Копирование
node_modulesс хоста (бинарники под другую ОС).
Что важно помнить
- Финальный образ = runtime + prod-зависимости +
dist+USER+CMD. - Graceful shutdown — ответственность кода приложения, Docker лишь посылает сигнал.
NODE_ENV=productionменяет поведение многих библиотек (Express, логгеры), поэтому задаётся в runtime-образе.
Мини-шпаргалка
- Multi-stage: deps → build → prod-deps → runner.
npm ci, cache mount,.dockerignore.CMD ["node", "dist/main.js"],USER node.0.0.0.0, SIGTERM, stdout.
Документация
Docker: Containerize a Node.js application, Node.js: Docker best practices.