Безпечна зміна домену 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, page cache, object cache, кеш 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-заміни серіалізованих даних.