Что такое build context и .dockerignore
На этой странице
Build context — набор файлов, который docker build передаёт сборщику; обычно это каталог, указанный последним аргументом (.). COPY видит только файлы из context, поэтому COPY ../file не работает. .dockerignore исключает файлы из context: ускоряет сборку, не ломает кэш случайными изменениями и не даёт попасть в образ node_modules, .git и .env с секретами.
Вопрос
Что такое build context и зачем нужен .dockerignore?
Что такое build context
docker build -t my-api .
# ^ context — текущий каталогCOPY package.json ./ # путь относительно корня context
COPY src ./srcФлаг -f меняет только путь к Dockerfile, но не context:
docker build -f docker/Dockerfile -t app . # context — корень проекта
docker build -f docker/Dockerfile -t app docker # context — папка docker:
# COPY package.json не найдёт файлЧем опасен большой context
Без .dockerignore в context попадает всё:
node_modules— сотни мегабайт, к тому же собранные под ОС хоста (native-модули под macOS не заработают в Linux);.git— история, иногда с удалёнными секретами;.env— настоящие пароли;dist,coverage,.nuxt,.output, логи, дампы базы.
Последствия: медленная передача context, ломающийся кэш (COPY . . видит изменение каждого лога) и утечка секретов в образ.
Пример .dockerignore для Node.js
# зависимости и артефакты сборки
node_modules
dist
.nuxt
.output
coverage
# git и CI
.git
.github
# секреты и локальные настройки
.env
.env.*
!.env.example
# логи и мусор
*.log
.DS_Store
# docker-файлы самой сборки
Dockerfile*
compose*.yaml
.dockerignoreСинтаксис похож на .gitignore: *, **, ! для исключения из исключений. Сборщик всё равно прочитает Dockerfile и .dockerignore, даже если они в списке, — просто их нельзя будет скопировать в образ через COPY.
Стратегия allowlist
Вместо перечисления лишнего можно разрешить только нужное:
*
!package.json
!package-lock.json
!tsconfig.json
!srcТак в образ гарантированно не попадёт ничего неожиданного.
Несколько контекстов
В монорепозитории иногда нужны файлы из соседнего пакета. BuildKit поддерживает именованные контексты:
docker buildx build --build-context shared=../packages/shared -t api .COPY --from=shared . /app/sharedЧастые ошибки
- Не создать
.dockerignore. - Отправить в context
node_modulesхоста и получить в Linux-образе бинарники под macOS. - Указать неправильный каталог context.
- Исключить файл, который потом нужен для
COPY, и получить ошибку «not found».
Что важно помнить
COPYработает только внутри context — выше корня выйти нельзя..dockerignoreзащищает одновременно скорость, кэш и секреты.- Для монорепозитория context обычно — корень репозитория, а Dockerfile лежит в пакете.
Мини-шпаргалка
- Последний аргумент
docker build— context. -fменяет Dockerfile, но не context..dockerignore:node_modules,.git,.env*,dist.- Allowlist через
*и!.