WP-CLI search-replace: как безопасно сменить домен WordPress без битых ссылок

Смена домена WordPress кажется простой задачей: заменить old-domain.ru на new-domain.ru в базе и перенести файлы. На практике URL хранятся не только в обычных текстовых полях. Они могут находиться в настройках темы, виджетах, page builder data, метаполях, опциях плагинов и PHP-serialized значениях. Обычный SQL REPLACE() способен повредить сериализованную строку, потому что внутри неё хранится длина текста.

Команда WP-CLI search-replace создана именно для безопасной массовой замены значений в базе WordPress. Официальная документация указывает, что команда корректно обрабатывает PHP serialized data и не изменяет primary key. Но даже правильный инструмент нужно использовать по плану: сначала backup и dry-run, затем замена, проверка сайта и только после этого переключение трафика.

Почему простая замена в SQL опасна

Представим, что в опции хранится сериализованный массив со строкой https://old.example. PHP serialization хранит не только значение, но и длину строки. Если новый домен длиннее или короче, прямой SQL REPLACE поменяет текст, но старое число длины останется. После этого WordPress или плагин может перестать читать значение целиком.

WP-CLI search-replace распознаёт такие структуры и пересобирает данные корректно. Поэтому для миграций WordPress это безопаснее, чем глобальная замена по дампу без понимания формата данных.

Шаг 1. Сделайте backup до любого search-replace

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

Минимально стоит зафиксировать:

• SQL dump базы;
• актуальную копию wp-content;
• старый и новый URL вместе со схемой HTTP/HTTPS;
• текущие значения home и siteurl;
• список внешних интеграций и webhook URL.

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

Шаг 2. Убедитесь, что WP-CLI работает с нужной установкой

До массовой замены проверьте, что команда выполняется в корне нужного WordPress и видит правильную базу. Полезны базовые команды вроде wp core is-installed и чтение текущих опций:

wp option get home
wp option get siteurl

Если на сервере несколько сайтов, ошибка рабочего каталога опаснее самой команды: технически корректный search-replace может быть выполнен не в той базе.

Шаг 3. Всегда начинайте с —dry-run

Официальная команда поддерживает режим --dry-run. Он показывает, что будет заменено, но не сохраняет изменения. Для смены домена базовый тест может выглядеть так:

wp search-replace 'https://old.example' 'https://new.example' --dry-run --skip-columns=guid

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

Нужно ли использовать —skip-columns=guid

В официальных примерах WP-CLI часто используется --skip-columns=guid. WordPress GUID исторически служит постоянным идентификатором записи и не обязан совпадать с публичным URL. Поэтому при обычной смене домена его часто сохраняют.

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

Шаг 4. Выполните реальную замену теми же параметрами

После проверки dry-run команда запускается без этого флага:

wp search-replace 'https://old.example' 'https://new.example' --skip-columns=guid

Лучше не менять одновременно несколько независимых вещей. Например, переход с HTTP на HTTPS и смену домена можно заранее свести к точной паре полного URL. Так меньше риск затронуть похожие строки или внешние адреса.

Почему важно искать полный URL, а не только имя домена

Замена old.example на new.example шире, чем замена https://old.example. Широкая строка может встретиться в email, технических идентификаторах, текстах инструкций или API-конфигурации. Чем точнее шаблон поиска, тем понятнее результат.

Иногда нужны несколько проходов: HTTP-вариант, HTTPS-вариант, URL с www и без него. Но каждый проход стоит сначала запускать как dry-run.

Что делать с таблицами плагинов

По умолчанию WP-CLI работает с таблицами текущей установки в соответствии с параметрами команды. Для нестандартных таблиц доступны дополнительные режимы, включая --all-tables-with-prefix. Это полезно, если плагин создал свои таблицы с тем же префиксом WordPress и действительно хранит там URL.

Использовать максимально широкий режим «на всякий случай» не стоит. Сначала нужно определить, какие таблицы принадлежат сайту и какие значения в них требуется менять. Особенно осторожно следует работать на сервере, где одна база содержит таблицы нескольких систем.

Multisite требует отдельной проверки

Для WordPress Multisite область замены сложнее: есть сетевые таблицы, отдельные сайты, domain mapping и разные URL. WP-CLI поддерживает параметры для работы с сетью, но до запуска нужно понять структуру конкретного multisite.

Миграцию сети лучше сначала повторить на staging-копии. Это позволяет проверить не только базу, но и вход в Network Admin, загрузку медиа, межсайтовые ссылки и работу mapped domains.

Search-replace не заменяет настройку DNS и веб-сервера

Команда меняет данные в базе. Она не переключает DNS, не выпускает SSL-сертификат, не меняет server_name в Nginx или VirtualHost Apache и не настраивает CDN. Поэтому успешный вывод WP-CLI ещё не означает завершённую миграцию.

Перед переключением домена нужно отдельно проверить DNS-записи, HTTPS, конфигурацию веб-сервера, Cloudflare или другой proxy/CDN, а также доступность нового домена из внешней сети.

После замены очистите кэш

Старый URL может остаться в page cache, object cache, CDN и сгенерированных CSS/JS-файлах. Поэтому после миграции очищают используемые уровни кэша и при необходимости пересобирают статические файлы page builder или оптимизационного плагина.

Важно различать данные базы и производные файлы. Если Elementor или другой builder генерирует CSS в uploads, search-replace в MySQL не обязан физически переписать содержимое уже созданного CSS-файла.

Проверьте home, siteurl и постоянные ссылки

После замены повторно получите:

wp option get home
wp option get siteurl

Затем откройте админку и сохраните структуру постоянных ссылок только если это требуется конкретной миграцией, либо используйте соответствующую WP-CLI команду для rewrite rules. Цель — убедиться, что WordPress генерирует новые URL и не отправляет пользователя обратно на старый домен.

301 redirect со старого домена нужен отдельно

Для SEO-переезда старый домен обычно продолжает принимать запросы и отдавать постоянный редирект на соответствующий URL нового домена. Такой redirect настраивается на уровне веб-сервера, CDN или другой инфраструктуры, а не через search-replace.

Нельзя ограничиваться редиректом всего старого домена на новую главную. Страница /catalog/item/ должна по возможности вести на эквивалентный новый URL. Это сохраняет пользовательские закладки и помогает поисковым системам понять переезд.

Что обязательно проверить после миграции

• главную и несколько внутренних страниц;
• формы и email-уведомления;
• медиафайлы и background images;
• canonical и Open Graph URL;
• robots.txt и sitemap;
• внутренние ссылки;
• авторизацию и личный кабинет;
• checkout и оплату для WooCommerce;
• webhooks, CRM и API-интеграции;
• редиректы со старого домена;
• ошибки браузерной консоли и mixed content.

Внешние URL могут не находиться в WordPress-базе

Search-replace обрабатывает базу данных. Но адрес старого домена может быть жёстко прописан в теме, custom plugin, JavaScript, конфигурации Docker, Nginx, GitHub Actions, внешней CRM или платёжном кабинете. Поэтому финальный аудит должен включать поиск по коду и список внешних сервисов.

Безопасная последовательность смены домена

1. Создать полную резервную копию.
2. Развернуть или проверить staging/новый сервер.
3. Проверить точные old URL и new URL.
4. Запустить WP-CLI search-replace с --dry-run.
5. Изучить количество замен и таблицы.
6. Выполнить реальную замену теми же параметрами.
7. Очистить кэш и пересобрать производные файлы.
8. Проверить сайт, SEO-метаданные и интеграции.
9. Переключить DNS и HTTPS по плану.
10. Настроить и протестировать 301 redirect со старого домена.

WP-CLI search-replace делает самую рискованную часть работы — замену данных в WordPress — значительно безопаснее, но качественная миграция всё равно остаётся комплексной задачей. A.S Groups может перенести WordPress на новый домен или сервер, выполнить замену с dry-run, проверить serialized data, редиректы, SEO и интеграции, а затем подтвердить работу сайта после переключения. Обсудить миграцию.