Безопасная смена домена WordPress через WP-CLI

Что подготовить перед сменой домена

Запускайте команды из корневой директории WordPress — там, где расположен файл <code>wp-config.php</code>. Пользователь, от имени которого выполняется WP-CLI, должен иметь доступ к файлам сайта и базе данных.

Перед операцией определите точные старый и новый адреса. Например, <code>https://old.example</code> и <code>https://new.example</code>. Не смешивайте в одной операции разные варианты протокола, наличие или отсутствие <code>www</code> и путь к подкаталогу.

• Убедитесь, что новый домен уже направлен на нужный сервер или окружение.
• Проверьте, что для нового домена выпущен SSL-сертификат, если используется HTTPS.
• Подготовьте резервную копию базы данных и убедитесь, что ее можно восстановить.
• Временно ограничьте доступ к сайту для редакторов и посетителей.
• Заранее проверьте настройки DNS, веб-сервера, CDN, почты и внешних интеграций.

wp db export backup-before-domain-change-$(date +%F-%H%M).sql
wp maintenance-mode activate

Почему не стоит выполнять массовую замену обычным SQL

В базе данных WordPress хранятся сериализованные структуры PHP. Вместе со значением в них записывается длина строки. Если заменить домен обычной функцией <code>REPLACE()</code>, длина может стать неправильной, и WordPress или плагин не сможет разобрать такие данные.

Проблема часто проявляется не сразу: сайт может открываться, но перестают работать виджеты, настройки темы, конструкторы страниц или отдельные плагины. WP-CLI распознает сериализованные значения и корректно обновляет их.

• Не выполняйте глобальный SQL-запрос без полной резервной копии.
• Не заменяйте домен простым поиском и заменой в дампе с помощью текстового редактора.
• Не редактируйте сериализованные значения в таблицах базы вручную.
• Помните, что WP-CLI изменяет базу данных, но не исправляет жестко заданные URL в PHP, JavaScript, CSS или конфигурациях веб-сервера.

Тестовый запуск через WP-CLI

Сначала выполните команду с параметром <code>--dry-run</code>. Она не изменяет базу данных, а только показывает, сколько совпадений будет найдено. Параметр <code>--all-tables-with-prefix</code> охватывает все таблицы с префиксом WordPress, включая таблицы плагинов, если они используют тот же префикс.

• В приведенной ниже команде замените домены на фактические адреса сайта.
• Не добавляйте завершающий слеш к одному домену, если у другого его нет.
• Запускайте команду с правами, обеспечивающими доступ к базе данных и файлам WordPress.

wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid \
--dry-run

Как оценить результат dry-run

Проверьте количество таблиц, столбцов и строк с совпадениями. Результат должен быть логичным для конкретного сайта: на небольшом проекте необычно большое количество совпадений может указывать на ошибку в адресе или слишком широкий шаблон поиска.

Если команда ничего не находит, проверьте протокол, поддомен, <code>www</code>, путь к подкаталогу и то, подключен ли WP-CLI к нужной базе данных. Для диагностики можно отдельно просмотреть значения основных URL.

• Сравните старый адрес с фактическим значением в настройках WordPress.
• Не запускайте замену только потому, что новый сайт открывается в браузере.
• Если сайт использует несколько вариантов старого адреса, например HTTP и HTTPS, запланируйте отдельные контролируемые операции.

wp option get home
wp option get siteurl

Выполнение замены домена

Если результат тестового запуска ожидаемый, повторите команду без <code>--dry-run</code>. Параметр <code>--skip-columns=guid</code> обычно оставляют намеренно: поле <code>guid</code> является стабильным идентификатором записи, а не обычным URL для навигации или SEO-редиректов.

Изменение GUID может создать лишние побочные эффекты для RSS и систем, которые используют это поле для идентификации записей. При этом решение зависит от сценария миграции, поэтому для нестандартных интеграций его стоит согласовать с разработчиком.

wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid

Если сайт работает в подкаталоге или использует multisite

Для WordPress в подкаталоге указывайте полный старый и новый адрес вместе с путем, если именно такая строка хранится в базе данных. Для multisite требуется дополнительная проверка: в базе могут находиться сетевые настройки, таблицы отдельных сайтов, домены блогов и правила веб-сервера.

Не ограничивайтесь проверкой только главной страницы. После операции проверьте каждый сайт сети, административную часть и URL, которые формируются для отдельных блогов.

• Создайте отдельную резервную копию перед изменением домена сети.
• Проверьте значения домена и пути в сетевых настройках.
• Убедитесь, что DNS и правила перенаправления охватывают все нужные поддомены или пути.

Очистка кэша и обновление зависимых настроек

После замены база данных уже будет содержать новый домен, но посетители могут получать старые страницы из кэша. Очистите кэш WordPress, кэш страниц, объектный кэш, кэш CDN и кэш на уровне веб-сервера, если он используется.

WP-CLI может очистить стандартный объектный кэш, но кэш конкретного плагина или CDN часто требует отдельной команды или действия в панели соответствующего сервиса.

• Очистите объектный кэш: <code>wp cache flush</code>.
• Перегенерируйте или очистите кэш страниц способом, который используется на сайте.
• Проверьте правила редиректов со старого домена на новый.
• Обновите URL в конфигурациях CDN, SMTP, платежных систем, вебхуков, OAuth и внешних API.
• Проверьте переменные окружения, конфигурационные файлы и код темы, где домен мог быть записан вручную.

wp cache flush
wp maintenance-mode deactivate

Проверка сайта после миграции

Проводите проверку не только в браузере, но и через HTTP-запросы и WP-CLI. Важно убедиться, что новый адрес используется в canonical, sitemap, REST API, медиафайлах и внутренних ссылках.

• Откройте главную страницу, несколько записей, страниц, категорий и страницу поиска.
• Проверьте, что изображения, файлы и шрифты загружаются с нового домена без mixed content.
• Проверьте canonical, hreflang, Open Graph и структурированные данные, если их формирует тема или SEO-плагин.
• Выполните запрос к REST API, например <code>/wp-json/</code>, и проверьте ответы на отсутствие ошибок авторизации и неожиданных перенаправлений.
• Проверьте XML-карту сайта, robots.txt, внутренние ссылки и редиректы со старых URL.
• Просмотрите журналы ошибок PHP и веб-сервера после открытия сайта.
• Убедитесь, что в админке работают редактор, загрузка медиафайлов, формы, кэширование и ключевые интеграции.

wp option get home
wp option get siteurl
curl -I https://new.example/
curl -I https://new.example/wp-json/

Типичные ошибки при смене домена

Чаще всего проблемы возникают не из-за самой команды, а из-за неполного плана миграции. Замена в базе данных не изменяет DNS, SSL, правила перенаправлений и файлы с жестко заданными адресами.

• Резервное копирование было пропущено или возможность восстановления не была проверена.
• Команда была запущена для неправильной базы данных или не из той директории WordPress.
• В поиске был указан HTTP вместо HTTPS, старый поддомен или неправильный путь.
• После операции остался кэш со старыми ответами и HTML старого домена.
• Старый домен отключили сразу, хотя он должен еще длительное время возвращать постоянный редирект на соответствующие новые URL.
• Некоторые URL остались в файлах темы, JavaScript, CSS, конфигурациях или настройках внешних сервисов.
• GUID изменили без необходимости или выполнили опасную SQL-замену сериализованных данных.