Docker Chokidar Hot Reload Fix | Cododel
CODODELDEV
EN / RU
Back to Deck
[fix]

Docker Chokidar Hot Reload Fix

ИСХОДНИК Docker
ВЕРСИЯ 1.0
АВТОР Cododel

Однострочный фикс для печально известной проблемы hot reload в Docker контейнерах при разработке с Node.js инструментами (Vite, Webpack, Directus Extensions и др.) на macOS и Windows.

Проблема

Когда вы монтируете локальную директорию как Docker volume:

volumes:
  - ./src:/app/src

File watching не работает на macOS и Windows потому что:

  • Docker использует виртуализированные файловые системы (VirtioFS, gRPC FUSE)
  • Нативные inotify события не пробрасываются от хоста в контейнер
  • chokidar (используется Vite, Webpack, nodemon и др.) никогда не детектит изменения
  • Результат: Вы меняете код, ничего не перезагружается

Затрагивает:

  • Vite dev server
  • Webpack dev server
  • Directus Extensions
  • Next.js dev mode
  • Любое Node.js приложение с hot reload

Решение

Включить режим polling для chokidar:

Terminal window
CHOKIDAR_USEPOLLING=true

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

Вариант 1: .env файл

Terminal window
CHOKIDAR_USEPOLLING=true

Вариант 2: docker-compose.yml

services:
  app:
    environment:
      - CHOKIDAR_USEPOLLING=true

Вариант 3: Dockerfile

ENV CHOKIDAR_USEPOLLING=true

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

РежимКак работаетПроизводительностьDocker совместимость
inotify (по умолчанию)Kernel события⚡ Быстро❌ Нет (на macOS/Win)
pollingПериодическая проверка файлов🐢 Медленнее✅ Да

Polling режим проверяет время модификации файлов с интервалом вместо надежды на kernel события, которые не работают через filesystem bridge Docker.

Пример: Directus Extensions

docker-compose.yml
services:
  directus:
    image: directus/directus:latest
    volumes:
      - ./extensions:/directus/extensions
    environment:
      - CHOKIDAR_USEPOLLING=true
      - EXTENSIONS_AUTO_RELOAD=true

Теперь ваши TypeScript extensions hot reload работают правильно!

Пример: Vite в Docker

services:
  frontend:
    build: .
    volumes:
      - ./src:/app/src
    environment:
      - CHOKIDAR_USEPOLLING=true
    ports:
      - '5173:5173'

Заметки по платформам

ПлатформаПроблемаФикс нужен
macOSVirtioFS не пробрасывает inotify✅ Да
Windows (WSL2)Ограничения 9P filesystem✅ Да
LinuxНативный inotify работает❌ Нет

Совет по производительности

Если polling кажется медленным, можно настроить интервал:

Terminal window
CHOKIDAR_USEPOLLING=true
CHOKIDAR_INTERVAL=100  # миллисекунды (по умолчанию: 100)

Меньше = быстрее детекция, выше нагрузка CPU.

TL;DR

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

[ ▲ 0 ]