Что такое Dockerfile
На этой странице
Dockerfile — текстовый рецепт сборки образа: базовый образ (FROM), рабочий каталог, установка зависимостей, копирование кода, сборка, пользователь и команда запуска. Инструкции выполняются сверху вниз, а изменяющие файловую систему (RUN, COPY, ADD) создают слои, которые кэшируются. Поэтому хороший Dockerfile упорядочен от редко меняющегося к часто меняющемуся: сначала lock-файлы и npm ci, потом исходники.
Вопрос
Что такое Dockerfile и как он превращается в образ?
Основная идея
FROM node:24-alpine # базовый образ: ОС-userland + Node.js
WORKDIR /app # рабочий каталог для следующих инструкций
COPY package.json package-lock.json ./
RUN npm ci # зависимости — отдельным слоем ради кэша
COPY . . # исходный код
RUN npm run build
EXPOSE 3000 # документация: приложение слушает 3000
USER node # не root
CMD ["node", "dist/main.js"] # команда запуска контейнераdocker build -t my-api .
docker run -p 3000:3000 my-apiКак Dockerfile превращается в образ
| Инструкция | Результат |
|---|---|
FROM | Слои базового образа |
RUN, COPY, ADD | Новый слой файловой системы |
WORKDIR, ENV, USER, EXPOSE, CMD, ENTRYPOINT, LABEL | Только метаданные (WORKDIR ещё и создаёт каталог) |
Если инструкция и её входные данные не изменились, BuildKit берёт слой из кэша. Как только слой изменился, все следующие пересобираются — подробнее в уроке про слои и кэш.
Почему порядок инструкций важен
# Плохо: любая правка кода заново запускает npm ci
COPY . .
RUN npm ci
# Хорошо: npm ci берётся из кэша, пока не изменился lock-файл
COPY package.json package-lock.json ./
RUN npm ci
COPY . .На реальном проекте это разница между сборкой за 5 секунд и за 2 минуты.
Что должен описывать хороший Dockerfile
- Фиксированную версию runtime (
node:24-alpine, а неnode:latest). - Воспроизводимую установку зависимостей (
npm ciпо lock-файлу). - Что попадает в образ, а что нет (вместе с
.dockerignore). - Пользователя, от которого работает процесс.
- Команду запуска в exec-форме (
["node", "dist/main.js"]). - Для production — multi-stage сборку, чтобы в финальный образ не попали компиляторы и devDependencies.
Парсер-директива syntax
# syntax=docker/dockerfile:1
FROM node:24-alpineПервая строка-комментарий подключает актуальную версию синтаксиса Dockerfile с возможностями BuildKit: RUN --mount=type=cache, --mount=type=secret, heredoc в RUN. В современных версиях Docker BuildKit включён по умолчанию.
Частые ошибки
- Копировать весь проект до установки зависимостей.
- Не использовать
.dockerignoreи тащить в образnode_modules,.gitи.env. - Оставлять devDependencies и исходники в production-образе.
- Запускать приложение от root.
- Использовать
npm installвместоnpm ci— сборка перестаёт быть воспроизводимой.
Что важно помнить
RUNвыполняется при сборке,CMD— при запуске контейнера.- Каждая инструкция, меняющая файлы, — новый слой; удаление файла в следующем слое не уменьшает образ.
- Dockerfile — часть кода проекта: его ревьюят, версионируют и проверяют в CI.
Мини-шпаргалка
FROM→WORKDIR→ lock-файлы →RUN npm ci→COPY . .→ build →USER→CMD.- Редко меняющееся — выше, часто меняющееся — ниже.
.dockerignoreобязателен.- Production — multi-stage.
Документация
Docker: Dockerfile reference, Docker: Building best practices.