wpnext
github wpnext
Cover Image for Настраиваем локальный сервер для разработки WordPress-сайта через wp-env

Настраиваем локальный сервер для разработки WordPress-сайта через wp-env

16 апреля 2026

Эта статья для тех случаев, когда WordPress-проект перерастает рамки «только темы» и превращается в полноценный сайт со своим набором плагинов, mu-плагинов, конфигом и данными. В этот момент локальный сервер становится инструментом повышения эффективности и качества разработки: он позволяет быстро поднимать одинаковое окружение, которое воспроизводимо у всей команды и снижает количество ошибок из-за различий в настройках.

Когда нужен локальный сервер

  • Когда над проектом работает несколько разработчиков и важно, чтобы окружение было одинаковым.
  • Когда в работе участвуют плагины, mu-плагины, CLI-команды, импорты и миграции, а не только код темы.
  • Когда нужно воспроизводимо дебажить баги, завязанные на версии PHP, MySQL, конфиг и расширения.
  • Когда не хочется поддерживать «ручную магию» настроек на каждом ноутбуке.

Стандартное решение wp-env

Для WordPress есть готовый, поддерживаемый сообществом инструмент: @wordpress/env.

wp-env позволяет поднимать окружение как на базе Docker, так и в облегчённом варианте через Playground на базе WASM. Дальше в статье разберём, как это устроено и как быстро запустить.

Простыми словами

По сути, вы описываете параметры проекта в .wp-env.json, а дальше запускаете среду одной командой. На выходе получаете рабочий сайт, доступ к WP-CLI и предсказуемое поведение на любой машине с Docker.

Составляющие и особенности подхода WPCraft

  1. Docker как runtime
    • Контейнеры изолируют окружение и убирают конфликт версий на хосте.
    • Проект не привязан к локальным настройкам PHP/MySQL конкретного разработчика.
  2. .wp-env.json как source of truth
    • Фиксирует PHP-версию, порт, маппинги wp-content, список подключаемых плагинов и флаги среды.
    • Из этого файла сразу видно, как именно должен запускаться проект.
  3. Маппинг рабочих директорий
    • В контейнер пробрасываются plugins, mu-plugins, themes, uploads.
    • Это позволяет работать с «живыми» файлами из репозитория и сразу видеть изменения в браузере.
  4. WP-CLI внутри окружения
    • В проекте есть отдельная команда make cli для входа в контейнер CLI (из темы app).
    • Это удобно для миграций, поиска/замены, обслуживания контента и проверок в правильном окружении.
  5. Локальный режим разработки. Быстрее ловятся ошибки и проще дебажить проблему «на месте».

Пример структуры репозитория (на примере реального проекта)

В этом проекте WordPress ведется как цельный сайт, а не как отдельная тема/плагин:

  • public/ — корень WordPress (ядро и служебные файлы)
  • public/wp-config.php — конфиг сайта
  • public/wp-content/themes/
    • app/ — рабочая дочерняя тема
    • blocksy/ — parent-тема
  • public/wp-content/plugins/ — проектные и внешние плагины
  • public/wp-content/mu-plugins/ — must-use плагины
  • public/wp-content/uploads/ — медиа и пользовательские файлы
  • .wp-env.json — конфигурация локального Docker-окружения
  • Makefile — набор команд управления для удобства (start, stop, reset, destroy, cli)

Такой layout помогает мыслить проектом целиком: тема, плагины, контент и настройки развиваются согласованно.

Как быстро поднять локальное окружение для разработки

1) Предусловия

  • Docker Desktop
  • Node.js LTS
  • Доступ к репозиторию

2) Пример .wp-env.json

{
  "core": "./public",
  "phpVersion": "8.2",
  "testsEnvironment": false,
  "plugins": [
    "https://downloads.wordpress.org/plugin/woocommerce.zip"
  ],
  "mappings": {
    "wp-content/plugins": "./public/wp-content/plugins",
    "wp-content/mu-plugins": "./public/wp-content/mu-plugins",
    "wp-content/themes": "./public/wp-content/themes",
    "wp-content/uploads": "./public/wp-content/uploads"
  },
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "WP_ENVIRONMENT_TYPE": "local"
  },
  "multisite": false,
  "port": 8811
}

3) Проверка

Запускаем командой npx wp-env start

  • Админка: http://localhost:8811/wp-admin
  • Логин: admin
  • Пароль: password

4) Полезные команды в ежедневной работе

Собираем Makefile — для удобства и автодополнения в терминале

start:
	wp-env start

start-update:
	wp-env start --update

stop:
	wp-env stop

restart:
	wp-env stop
	wp-env start

reset:
	wp-env reset

cli:
	npx wp-env run cli --env-cwd=wp-content/themes/app sh

destroy:
	npx wp-env destroy

Пример команд:

make stop        # остановить окружение
make restart     # перезапуск
make start-update# старт с обновлением образов
make reset       # сброс данных окружения
make destroy     # полное удаление окружения wp-env
make cli         # shell в wp-env CLI-контейнере

Преимущества такого подхода

  • wp-env — быстрый способ стандартизировать локальную WordPress-разработку через Docker.
  • Главная идея: один конфиг (.wp-env.json) и воспроизводимый запуск у всей команды.
  • В сложных WordPress-проектах стоит мыслить не темой отдельно, а сайтом как системой.
  • Критично маппить wp-content директории и работать с ними как с частью репозитория.
  • Makefile поверх wp-env снижает порог входа и делает команды очевидными.
  • WP-CLI внутри контейнера — обязательная часть workflow для операционных задач.
  • Типовая структура репозитория должна явно показывать, где код, где контент и где конфиг среды.
  • Такой подход особенно полезен, когда на сайте много плагинов и есть зависимость от их взаимодействия.
  • Следующий шаг эволюции: автоматизировать импорт данных и smoke-check после make start.

Одно из главных преимуществ для меня — это позволяет собрать конфигурацию под любой хостинг. Хоть обычный виртуальный хостинг, хоть под выделенный сервер, хоть под облачные контейнеры.

Итого

wp-env хорошо работает как «инфраструктурный минимум»: быстро стартует, прозрачно настраивается и покрывает реальные задачи команды разработки. Даже для очень сложных проектов.

Если оформить вокруг него понятные правила (структура репозитория, команды, data-flow, CLI-практики), локальная разработка перестает быть источником случайностей и становится предсказуемой инженерной системой.

Ссылки

Ещё почитать