Исправление Docker Hot Reload: CHOKIDAR_USEPOLLING

27.12.2025

Если вы когда-нибудь монтировали локальную директорию в Docker контейнер и удивлялись, почему ваш Vite/Webpack/Node.js hot reload просто… не работает — вы не одиноки.

Fix ПОЛНОЕ РЕШЕНИЕ

Проблема

Вы меняете файл. Ничего не перезагружается. Рестартите контейнер. Всё ещё ничего. Тратите часы на дебаг webpack конфигов, только чтобы обнаружить что это ограничение файловой системы.

Docker на macOS и Windows использует виртуализированные файловые системы (VirtioFS, gRPC FUSE). Нативные inotify события — на которые полагаются инструменты типа chokidar — не пробрасываются от вашего хоста в контейнер.

Затронутые инструменты:

Vite
Webpack
Directus Extensions
Next.js dev mode
Nodemon
Любой Node.js инструмент использующий chokidar

Решение

Одна переменная окружения:

CHOKIDAR_USEPOLLING=true

Добавьте в ваш .env, docker-compose.yml или Dockerfile.

Всё. Hot reload работает.

Почему это работает

Вместо ожидания filesystem событий, которые никогда не придут, polling режим проверяет время модификации файлов с регулярными интервалами. Немного медленнее, но реально работает через virtual filesystem bridge Docker.

Режим	Скорость	Работает в Docker
inotify	⚡ Быстро	❌ macOS/Windows
polling	🐢 Ок	✅ Везде

Реальный пример

Я поддерживаю Directus фреймворк, где hot reload для TypeScript extensions не работал на macOS. Разработчики вручную рестартили контейнеры после каждого изменения.

Одна строка в конфиге environment исправила это для всех:

environment:
  - CHOKIDAR_USEPOLLING=true
  - EXTENSIONS_AUTO_RELOAD=true

TL;DR

Проблема: Hot reload сломан в Docker на macOS/Windows
Причина: Нативные file события не проходят через virtual filesystems
Фикс: CHOKIDAR_USEPOLLING=true

Хватит рестартить контейнеры. Начинайте шипать.

[СТАТУС: HOT_RELOAD_ENABLED]