Настройка Gulp + BrowserSync для WordPress в Docker

Да — livereload (BrowserSync) можно настроить для WordPress в Docker через Gulp: обычно запускают Gulp + BrowserSync на хосте, проксируют сайт (proxy: “http://localhost:8080”) и делают watch/stream для .scss/.js/.php (browsersync.stream() для CSS, browsersync.reload() для JS/PHP). Ключевые параметры: proxy, port/host, socket.domain, watchOptions.usePolling и правильные пути/volumes; ниже — готовые примеры, варианты запуска (хост vs контейнер) и чек‑лист диагностики.

Содержание

• Краткий обзор решения
• Настройка BrowserSync (livereload) в Gulp для Docker WordPress
• Gulp и BrowserSync: запуск на хосте vs внутри контейнера
• Изменения в docker-compose.yml для BrowserSync
• Пример рабочего Gulp-задачи и docker-compose.yml
• Диагностика: почему proxy не работает и как это исправить
• Источники
• Заключение

Краткий обзор решения

Идея простая: BrowserSync проксирует ваш Docker‑сайт и внедряет клиентский скрипт, который слушает сервер BrowserSync и перезагружает страницу при изменениях. Gulp компилирует SASS/JS в папку темы (wp/wp-content/themes/main) — после успешной сборки нужно либо инжектить стиль через browsersync.stream(), либо вызывать browsersync.reload() после записи JS/PHP. Частая причина проблем — неверные watch‑пути, отсутствие событий файловой системы в Docker (решается usePolling) или конфликт доменов/портов (assets грузятся с localhost:8080, а вы открыли сайт на 3000).

Настройка BrowserSync (livereload) в Gulp для Docker WordPress

Что важно указать в browsersync.init:

• proxy: URL вашего контейнера — обычно “http://127.0.0.1:8080” или “http://localhost:8080”.
• port: порт BrowserSync (по умолчанию 3000) — на нём будет открываться проксированный сайт.
• ui.port: интерфейс BrowserSync (3001) — опционально.
• notify: false — отключает всплывашки.
• socket.domain: если клиент не подключается к WS, явно укажите домен/порт, например ‘localhost:3000’.
• watchOptions: { usePolling: true, interval: 500 } — обязателен на Mac/Windows/WSL при проблемах с событиями.
• snippetOptions / rewriteRules — для кейсов с абсолютными URL (см. ниже).

Пример опций (с пояснениями):

browsersync.init({
 proxy: 'http://127.0.0.1:8080', // проксируем сайт из Docker
 host: 'localhost',
 port: 3000, // адрес для браузера: http://localhost:3000
 ui: { port: 3001 },
 open: true,
 notify: false,
 socket: { domain: 'localhost:3000' }, // если клиент пытается подключиться не туда
 watchOptions: { usePolling: true, interval: 500 }, // решает проблемы с FS-событиями
 snippetOptions: {
 rule: {
 match: /<\/body>/i,
 fn: function (snippet, match) { return snippet + match; }
 }
 }
});

Как правильно реагировать на изменения:

• SASS: после компиляции делать .pipe(browsersync.stream({match: ‘**/*.css’})) — CSS инжектится без полной перезагрузки.
• JS: после сборки вызвать browsersync.reload() (или .on(‘end’, browsersync.reload)).
• PHP: наблюдать за файловой системой темы и на изменение делать browsersync.reload().

Пример паттернов watch:

• ‘src/scss/**/*.scss’ → компиляция → browsersync.stream()
• ‘src/js/**/*.js’ → сборка → browsersync.reload()
• ‘wp/wp-content/themes/main/**/*.php’ → browsersync.reload()

Совет: вместо полагания только на опцию files у BrowserSync используйте Gulp‑watch и явный вызов reload/stream — так вы контролируете порядок (сначала сборка, затем reload).

Ссылки по опциям BrowserSync: документация опций — https://browsersync.io/docs/options и про proxy — https://browsersync.io/docs/options#option-proxy.

Gulp и BrowserSync: запуск на хосте vs внутри контейнера

Коротко — что выбрать?

1. Запуск Gulp/BrowserSync на хосте (рекомендуем по умолчанию)

• Плюсы: простая настройка, быстро править зависимости (npm), легче дебажить, меньше оверхеда.
• Минусы: на macOS/Windows иногда проблемы с событиями файловой системы (решается polling), может понадобиться включить общий доступ к папкам Docker.
• Реализация: proxy → http://localhost:8080 (как в примере выше).

2. Запуск Gulp/BrowserSync в отдельном контейнере (node image)

• Плюсы: единообразная среда, удобно для CI/команды; можно гарантировать версии node/gulp.
• Минусы: сложнее настроить network/volumes, на mac/win может быть хуже с watch (опять polling), нужно пробросить порты 3000/3001 наружу.
• Реализация: в browsersync.init использовать proxy: ‘http://wordpress:80’ (имя сервиса docker‑compose) и host: ‘0.0.0.0’, проброс портов “3000:3000”.

Небольшой хит: на Linux можно использовать network_mode: host для контейнера BrowserSync (тогда proxy = http://localhost:8080 работает внутри контейнера), но это не портируемо и не поддерживается Docker Desktop на Mac/Windows.

Подробнее про Gulp — https://gulpjs.com/docs/en/getting-started/quick-start.

Изменения в docker-compose.yml для BrowserSync

Если вы запускаете Gulp на хосте — чаще всего docker-compose менять не нужно: у вас уже ports: “8080:80” — это достаточно. Однако учтите:

• volumes: убедитесь, что тема смонтирована в контейнер и на хосте (у вас ./wp/wp-content:/var/www/html/wp-content — OK).
• На macOS/Windows: если замечаете медленную работу или отсутствие изменений — попробуйте добавить опции производительности (Docker Desktop) или включить polling в BrowserSync.
• Если BrowserSync в контейнере — добавьте сервис browsersync и проброс портов 3000/3001, прим.:

browsersync:
 image: node:18
 container_name: bs_local
 working_dir: /var/www
 volumes:
 - ./:/var/www
 command: sh -c "npm ci && npx gulp"
 ports:
 - "3000:3000"
 - "3001:3001"
 depends_on:
 - wordpress
 environment:
 - CHOKIDAR_USEPOLLING=true

• network_mode: host — нельзя использовать на Docker Desktop (Mac/Win), только на Linux и с осторожностью.

Если WordPress генерирует абсолютные URL (siteurl = http://localhost:8080), а вы хотите удобно работать через BrowserSync (http://localhost:3000), подумайте о:

• временной смене siteurl на http://localhost:3000 в базе при разработке, либо
• использовании rewriteRules в BrowserSync, чтобы переписать ссылки с 8080 на 3000 (см. пример ниже).

Пример рабочего Gulp-задачи и docker-compose.yml

1. Рекомендуемый вариант: Gulp и BrowserSync на хосте (простая и надёжная схема)

Gulpfile (пример, gulp 4):

// gulpfile.js
const { src, dest, watch, series, parallel } = require('gulp');
const sass = require('gulp-sass')(require('sass'));
const plumber = require('gulp-plumber');
const browsersync = require('browser-sync').create();

const theme = './wp/wp-content/themes/main';
const scssSrc = 'src/scss/**/*.scss';
const jsSrc = 'src/js/**/*.js';

function styles() {
 return src(scssSrc, { sourcemaps: true })
 .pipe(plumber())
 .pipe(sass().on('error', sass.logError))
 .pipe(dest(`${theme}/assets/css`, { sourcemaps: '.' }))
 .pipe(browsersync.stream({ match: '**/*.css' }));
}

function scripts(done) {
 src(jsSrc)
 .pipe(plumber())
 .pipe(dest(`${theme}/assets/js`))
 .on('end', function () { browsersync.reload(); done(); });
}

function serve(done) {
 browsersync.init({
 proxy: 'http://127.0.0.1:8080',
 port: 3000,
 ui: { port: 3001 },
 open: true,
 notify: false,
 socket: { domain: 'localhost:3000' },
 watchOptions: { usePolling: true, interval: 500 },
 // rewriteRules: [{ match: /http:\/\/127.0.0.1:8080/g, replace: 'http://localhost:3000' }]
 });
 done();
}

function watchFiles() {
 watch(scssSrc, styles);
 watch(jsSrc, scripts);
 watch(`${theme}/**/*.php`).on('change', browsersync.reload);
}

exports.default = series(serve, parallel(styles, scripts), watchFiles);

Особенности:

• открывайте сайт через http://localhost:3000 (BrowserSync).
• если CSS не инжектится — проверьте, откуда загружается CSS (3000 или 8080).

2. Альтернативный вариант: BrowserSync в контейнере — пример части docker-compose (добавить browsersync сервис, как выше). В этом случае в Gulp используйте proxy: ‘http://wordpress:80’ и host: ‘0.0.0.0’.

Полезная опция для переписывания абсолютных URL:

rewriteRules: [
 { match: /http:\/\/localhost:8080/g, replace: 'http://localhost:3000' }
]

Это пригодится, если WordPress отдаёт CSS/JS с абсолютными ссылками на порт 8080.

Диагностика: почему proxy не работает и как это исправить

Почему при proxy: “http://localhost:8080” у вас открывается 3000 (это нормально) — но reload не срабатывает? Проверяем по шагам:

1. BrowserSync client вообще внедряется?

• Откройте http://localhost:3000 → Просмотреть исходный код → найдите ссылку на browser-sync-client.js (обычно /browser-sync/browser-sync-client.js).
• Или сделайте: curl -s http://localhost:3000 | grep -i “browser-sync”.

2. WebSocket соединение в браузере падает?

• Открой DevTools → Console/Network → ищите ошибки ws://localhost:3000 или 404 на client js. Если есть — добавьте option socket: { domain: ‘localhost:3000’ }.

3. Gulp‑watch не срабатывает (ни одна задача)?

• Вставьте console.log() в таски и сохраните файл — проверьте, запускается ли таск.
• На macOS/Windows/WSL часто требуется polling: watchOptions.usePolling = true.

4. CSS инжектится, но не видно изменений?

• Проверьте, откуда загружается CSS: если с 8080 (абсолютный URL), BrowserSync не сможет инжектить стили в документ, который грузит файл с другого origin. Смените siteurl на 3000 или используйте rewriteRules.

5. PHP/JS изменения не приводят к reload?

• Убедитесь, что после записи файлов вы вызываете browsersync.reload(). Для PHP можно положиться на BrowserSync files/watch, но лучше вызывать reload из Gulp.

6. Проверки на уровне ОС/докера:

• docker ps — проверьте, что порт 8080 проброшен.
• lsof -i :3000 (или netstat) — слушает ли процесс browsersync.
• При проблемах с сетью в контейнерах (если BrowserSync в контейнере) — пробросьте порты 3000/3001 и используйте proxy: ‘http://wordpress:80’.

7. CSP / Security / плагины кеширования:

• Иногда плагины безопасности/кеширования могут блокировать внедрение скрипта. Отключите кеш/минимайзинг на время разработки.

8. Логируйте: в Gulp добавьте listeners для browsersync events или просто добавьте console.log при change — это часто быстро указывает, где затык.

Короткий чек‑лист:

• Открываю сайт через http://localhost:3000? (да/нет)
• В HTML есть browser-sync-client.js?
• В консоли браузера ошибки WS/CSP?
• Gulp‑таски действительно выполняются?
• usePolling включён при Docker на Mac/Win/WSL?
• CSS/JS грузятся с 3000 или с 8080 (проверьте Network)?

Источники

• BrowserSync — опции (proxy, socket, watchOptions): https://browsersync.io/docs/options
• BrowserSync — подробности про proxy: https://browsersync.io/docs/options#option-proxy
• Gulp — быстрый старт: https://gulpjs.com/docs/en/getting-started/quick-start
• Docker Compose — документация: https://docs.docker.com/compose/
• WordPress Docker (официальный образ): https://hub.docker.com/_/wordpress

Заключение

Настроить livereload (BrowserSync) для WordPress в Docker с помощью Gulp реально и обычно выполняется запуском Gulp + BrowserSync на хосте, проксированием http://localhost:8080 и использованием browsersync.stream() для CSS и browsersync.reload() для JS/PHP; не забудьте watchOptions.usePolling при проблемах с FS‑событиями и socket.domain, если клиент не подключается. Если что-то не работает — пройдите чек‑лист из раздела диагностики: в 90% случаев причина — неправильный watch, абсолютные URL (8080 vs 3000) или отсутствие событий файловой системы. Удачи с настройкой gulp + browsersync + docker wordpress — если хотите, могу подправить ваш gulpfile или дать конкретную версию Gulp‑файла под ваш текущий src-путь.