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

Почему прямой SQL или sed могут повредить WordPress

WordPress часто хранит настройки в формате PHP serialization. В такой структуре вместе с текстом записывается его длина. Например, строка может выглядеть так: a:1:{s:3:"url";s:18:"https://old.example";}. Если заменить адрес на более длинный или короткий без пересчета длины, PHP не сможет корректно прочитать значение.

Такие данные встречаются в wp_options, wp_postmeta, wp_usermeta, таблицах плагинов и полях конструкторов страниц. Возможные последствия — исчезновение настроек, ошибки плагинов, пустые виджеты или сообщения о поврежденных serialized data.

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

• Не редактируйте дамп базы обычным поиском и заменой, если не проверяете все форматы данных.
• Не заменяйте значения только в wp_options: адреса могут находиться в контенте, метаполях и таблицах плагинов.
• Учитывайте точный вариант адреса: http или https, www или без www, а также наличие завершающего слеша.

Подготовка к замене домена

Перед запуском команды определите корневую директорию нужной установки WordPress. Обычно в ней находится wp-config.php. Это особенно важно на сервере с несколькими сайтами: ошибка в пути может привести к работе с другой базой данных.

Создайте резервную копию базы данных и убедитесь, что ее можно восстановить. Backup должен быть доступен до начала операции, а не создаваться после неудачного search-replace. Если сайт критически важен, сначала протестируйте миграцию на staging-копии.

Также проверьте, доступен ли WP-CLI от имени пользователя, имеющего доступ к файлам WordPress и базе данных. Команду лучше запускать из корня сайта, а не из случайной директории.

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

cd /var/www/example.com
wp core is-installed
wp option get home
wp option get siteurl

Какие варианты URL нужно учитывать

Одна миграция не всегда охватывает все варианты адреса. Например, в базе могут остаться http://old.example, https://old.example, http://www.old.example или URL с завершающим слешем. Сначала определите, какие значения действительно используются, а затем выполняйте отдельные контролируемые замены.

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

Базовая команда WP-CLI search-replace

Для типичной миграции домена начните с dry-run и исключите поле guid. Параметр --all-tables-with-prefix охватывает все таблицы, имена которых начинаются с префикса WordPress, а не только стандартные wp_posts или wp_options.

Значения в кавычках нужно передавать точно. Если URL содержит специальные символы, используйте одинарные кавычки в shell или другой безопасный способ экранирования.

• --dry-run показывает ожидаемые изменения, но не записывает их в базу.
• --all-tables-with-prefix позволяет проверить таблицы многих плагинов с соответствующим префиксом.
• --skip-columns=guid исключает колонку guid из замены.
• После анализа результата dry-run ту же команду можно выполнить без --dry-run.

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

Выполнение после проверки

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

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

Как проверить результат dry-run

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

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

Если в отчете появились таблицы плагина или нестандартные колонки, проверьте документацию этого плагина. Некоторые продукты хранят данные в формате JSON, в сжатом или зашифрованном виде. WP-CLI корректно обрабатывает стандартные сериализованные PHP-структуры, но не может безопасно распаковать произвольный неизвестный формат.

• Проверьте названия таблиц и колонок в отчете.
• Сопоставьте количество совпадений с ожидаемым объемом контента и настроек.
• Выясните причину, если замена не находит ни одного значения.
• Не запускайте операцию повторно без необходимости: повторная замена может быть лишней или изменить данные, если строки поиска пересекаются.

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

Что делать с GUID и пользовательскими таблицами

Колонка guid в wp_posts имеет специальное назначение. Это глобальный идентификатор записи, а не обычное поле для отображения текущего URL страницы. Поэтому при типичной миграции ее часто пропускают с помощью --skip-columns=guid.

Если есть конкретная причина изменить GUID, это нужно делать осознанно после оценки последствий. Не включайте это поле только потому, что в нем остался старый адрес. Изменение GUID не является стандартным способом исправления canonical URL, внутренних ссылок или адреса сайта.

Параметр --all-tables-with-prefix охватывает таблицы с префиксом, указанным в wp-config.php. Если плагин создал таблицу с другим префиксом или без стандартного префикса, она может не попасть в операцию. Такие таблицы нужно проверять отдельно и обрабатывать только согласно документации плагина либо после анализа их структуры.

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

Проверка сайта после search-replace

После фактической замены проверьте значения home и siteurl, откройте главную страницу, несколько записей, страницы с медиафайлами и формы. Отдельно протестируйте авторизацию, админ-панель, поиск, корзину и checkout, если сайт использует электронную коммерцию.

Проверьте, не остались ли ссылки на старый домен в контенте, виджетах, меню и настройках плагинов. Для этого можно повторно запустить search-replace в режиме dry-run со старым адресом. Ожидаемый результат — отсутствие совпадений или понятные остатки в полях, которые намеренно не изменялись.

После миграции очистите кеш WordPress, серверный кеш, CDN и кеш плагинов, если они используются. Также проверьте robots.txt, XML-карту сайта, SSL-сертификат, редиректы со старого домена и настройки внешних интеграций.

• Проверьте home и siteurl через WP-CLI.
• Выполните повторный dry-run для старого URL.
• Просмотрите страницы с разными типами контента и изображениями.
• Проверьте отправку email, API, webhook и платежные интеграции.
• Зафиксируйте ошибки PHP и ответы HTTP 4xx/5xx после миграции.

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

Типичные ошибки и безопасная стратегия восстановления

Самая частая ошибка — запуск команды без резервной копии или с неправильным путем к WordPress. Другие риски: перепутанный протокол, замена только в стандартных таблицах, ненужное изменение GUID и попытка обработать с помощью WP-CLI зашифрованные или нестандартно сжатые данные.

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

После восстановления повторите процесс на staging: сначала проверьте точные URL, затем выполните dry-run, просмотрите таблицы и только после этого запустите замену. Такой подход обычно быстрее ручного исправления поврежденных serialized data.

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