Порядок миграции WordPress → Rankbeam

Пошаговый порядок замены SEO-стека WordPress (Yoast или Rank Math) на Rankbeam. По умолчанию импортёры заполняют пустые поля в целевой системе; --overwrite явно разрешает замену значений. Пробные запуски ничего не записывают, а исходная база WordPress остаётся без изменений. Перед импортом создайте резервные копии источника и целевой системы.

Это практическое дополнение к миграции с WordPress, где подробно описаны сопоставление полей, обработка шаблонных токенов и ключи источника. Та страница объясняет, что переносится; эта — как и в каком порядке.

Что понадобится

• Core (rankbeam/laravel-seo) для импорта метаданных и seo:audit.
• Pro (rankbeam/laravel-seo-pro), только если вы также переносите перенаправления: таблица seo_redirects относится к Pro.
• Контент, уже представленный моделями Laravel, например App\Models\Post, с трейтом HasSEO и способом сопоставить slug WordPress с моделью: ключом маршрута модели или столбцом, указанным через --match-by.

Как устроена миграция

Строки WordPress привязаны к URL или записи; строки seo_meta Rankbeam полиморфны — связаны с моделью Eloquent. Импорт сопоставляет каждую строку WordPress с одной из ваших моделей. Возможны три результата; каждый запуск показывает их распределение:

Результат	Значение	Действие
matched	строка привязана к модели, данные записаны в seo_meta	не требуется
url-only	строке не соответствует модель или не указан --model	решите, нужна ли странице модель или перенаправление
unmapped	в строке есть данные без соответствующего поля Core 3, прежде всего author	перенесите их в подходящее место, например хук getSEOAuthor()

---

Шаг 0 — Параллельная работа без переключения

Запустите Rankbeam рядом с работающим сайтом. Добавьте трейт HasSEO в модели и выводите теги через фасад или директиву, но пока не удаляйте WordPress или его SEO-плагин. На этом этапе ничего не импортируется и не удаляется: вы только проверяете, что новый стек запускается.

Если во время перехода новое приложение Laravel и старый сайт WordPress работают на одном хосте, держите их на разных путях до шага 5.

Шаг 1 — Импорт метаданных, сначала пробный запуск

Всегда начинайте с --dry-run: этот режим ничего не записывает и выводит полный проверочный отчёт о том, что произошло бы при импорте.

# Yoast, from the live WordPress database (configure the connection first)
php artisan seo:import-from yoast \
  --connection=wordpress \
  --model="App\Models\Post" \
  --redirects-csv=storage/app/redirects.csv \
  --dry-run

# Rank Math is identical — just swap the source key
php artisan seo:import-from rank-math --connection=wordpress --model="App\Models\Post" --dry-run

# From a CSV export instead of the live DB
php artisan seo:import-from wordpress-csv --file=storage/app/wp-export.csv --model="App\Models\Post" --dry-run

Полезные параметры; полный список доступен через php artisan seo:import-from --help:

Параметр	Назначение
--model=	полное имя класса целевой модели (параметр можно повторять; импортёры WordPress привязывают одну модель за запуск — запускайте отдельно для каждого типа контента)
--match-by=	столбец модели для сопоставления со slug; по умолчанию ключ маршрута
--post-type=	ограничить чтение базы этими типами записей; по умолчанию post и page
--connection=	подключение к базе с таблицами WordPress
--table=	префикс таблиц WordPress; по умолчанию wp_
--locale=	локаль, для которой записываются строки seo_meta
--redirects-csv=	также вывести кандидатов на перенаправление в этот файл для шага 3
--site-url=	URL старого сайта для получения путей из абсолютных URL
--overwrite	заменить существующие непустые seo_meta; по умолчанию заполняются только пустые поля
--limit=	ограничить число исходных строк; удобно для первого прохода
--json	машиночитаемый отчёт

Если пробный запуск дал ожидаемый результат, уберите --dry-run, чтобы применить импорт:

php artisan seo:import-from yoast --connection=wordpress --model="App\Models\Post" --redirects-csv=storage/app/redirects.csv

По умолчанию импорт идемпотентен и заполняет только пустые поля. В этом режиме его можно безопасно повторять: он не перезапишет метаданные, уже отредактированные в Rankbeam. Явное разрешение перезаписи меняет это поведение.

Шаг 2 — Прочитайте и сохраните проверочный отчёт

Каждый запуск выводит Verification report — числа, которые нужно проверить перед удалением старой системы. Сохраните отчёт в файл:

php artisan seo:import-from yoast --connection=wordpress --model="App\Models\Post" --json > storage/app/import-report.json

Что проверить:

• matched должно совпадать с ожидаемым числом страниц с SEO-метаданными.
• url-only — список страниц, которым не нашлось модели. Для каждой решите, нужна ли модель, перенаправление (шаг 3) или ничего.
• truncated перечисляет поля, сокращённые до размера столбца seo_meta. Проверьте эти заголовки и описания.
• unmapped перечисляет исходные данные без столбца в Core 3, причём явно показывает каждое отдельное значение author. Авторы не хранятся в столбце: за них отвечает getSEOAuthor(). Отчёт нужен, чтобы вы осознанно перенесли их в другое место, а не обнаружили потерю через несколько месяцев.

Шаг 3 — Импорт перенаправлений в Pro

Импортёр ядра никогда не записывает seo_redirects — это таблица Pro. Он выдаёт CSV с фиксированным версионируемым форматом: формат CSV перенаправлений v1, source_path,target_url,status_code,note. Импортируйте его в Pro, начав с пробного запуска:

php artisan seo-pro:redirects-import storage/app/redirects.csv --dry-run
php artisan seo-pro:redirects-import storage/app/redirects.csv

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

Шаг 4 — Проверка через seo:audit --strict

Сделайте бесплатный аудит внутри процесса обязательной проверкой миграции. --strict возвращает ненулевой код завершения, если проблема есть на любой странице, поэтому подходит для CI и проверки перед переключением:

php artisan seo:audit --model="App\Models\Post" --strict

Аудит проверяет модели и резолвер: наличие и длину заголовка и описания, изображение OG, конфликты robots, формат канонического URL. Проверки отрендеренного HTML и действующих канонических адресов, а также оценка 0–100 относятся к сканированию Pro. Если у вас есть Pro, запустите и его. См. бесплатный SEO-аудит.

Затем выборочно проверьте несколько настоящих страниц в браузере: откройте исходный код и убедитесь, что <title>, <meta name="description">, canonical, robots и теги OpenGraph выводят импортированные значения.

Шаг 5 — Проверка ДО удаления старого пакета или таблицы

Не удаляйте базу WordPress, SEO-плагин или старый пакет, пока не выполнены все условия:

• [ ] Импорт запущен для каждого типа контента, по одному --model за запуск.
• [ ] Сохранённый проверочный отчёт показывает ожидаемое число matched без неожиданных строк url-only.
• [ ] Каждое нужное значение unmapped author перенесено в подходящее место.
• [ ] Перенаправления импортированы в Pro через seo-pro:redirects-import, и несколько старых URL действительно возвращают 301 на новые.
• [ ] php artisan seo:audit --strict завершается с кодом 0.
• [ ] (Pro) php artisan seo:doctor не сообщает об оставшейся старой таблице seo или конфликте config/seo.php.
• [ ] Отрендеренные страницы выборочно проверены в браузере.

Поскольку по умолчанию импортёры заполняют только пустые поля и идемпотентны, шаг 1 в этом режиме можно повторять до прохождения проверки без перезаписи заполненных метаданных. Старые данные всё ещё находятся в WordPress. Этот вывод не относится к запуску с разрешённой перезаписью.

Шаг 6 — Вывод старой системы из эксплуатации

Только после выполнения списка шага 5 отключите сайт WordPress, затем удалите его базу или таблицы и старый SEO-пакет. Сохраняйте резервную копию базы, пока не убедитесь, что новый стек корректно обслуживает сайт в продакшене.

Откат

При настройках по умолчанию шаги 1–4 добавляют данные в seo_meta без замены заполненных значений. Перенаправления проверяются и обратимы: добавленные правила можно удалить. Данные WordPress остаются без изменений. До шага 6 откат означает «продолжить обслуживать сайт через WordPress», после шага 6 — «восстановить резервную копию WordPress». Если вы разрешили перезапись метаданных или существующих перенаправлений, для их восстановления нужна также резервная копия целевой системы, сделанная до импорта.

---

Переходите с SEO-пакета Laravel — ralphjsmit, artesaos или Spatie? См. миграцию из других пакетов Laravel.