Миграция на Headless CMS — это не перенос контента, а трансляция схемы между двумя несовместимыми моделями данных. Относиться к этому как к задаче «скопировать и вставить» — главная причина, почему столько миграций застревают на полпути или тихо пересобираются через полгода. Сбои здесь не экзотические: это несоответствие типов полей, «сплющенные» связи, которые нужно переопределить как ссылки, языковые структуры, которые не сопоставляются, и URL-адреса ассетов, зашитые в богатый текст.
В этом руководстве миграция разбита на этапы, чтобы каждый такой сбой обнаружился во время аудита, а не в продакшене. То же самое справедливо и для других типов платформ: например, миграция платформ электронной коммерции зависит от аналогичных решений о том, что переносить, что сломается и когда производить переключение.
TL;DR: Четыре вещи, которые ломаются при миграции на Headless CMS
Трансляция схемы, а не перенос контента — это операция, из-за которой ломается миграция на Headless CMS. Проблема сначала проявляется в виде несоответствия типов полей: гибкое поле богатого текста в WordPress, принимающее вложенный HTML и встроенные шорткоды, не имеет прямого эквивалента в строгом поле Contentful, Strapi или Storyblok, и ничто не сигнализирует об этом, пока валидация не отклонит импорт.
Наша инженерная команда проводит аудит экспортов из устаревших CMS на предмет несоответствия типов полей, потерянных шорткодов и глубины графа ссылок перед каждым запуском headless-переключения. Паттерн повторяется: контент, который выглядит чистым в экспорте CSV, дает сбой в тот момент, когда попадает в структурированную схему.
Перед написанием скрипта миграции экспортируйте исходную модель контента и сопоставьте каждый тип поля с библиотекой полей целевой платформы. Глубоко вложенные цепочки ссылок — это то, что требует перепроектирования, а не просто маппинга.
В этой статье рассматриваются несоответствие типов полей, моделирование ссылок и связей, локаль на запись (locale-per-entry) против локали на поле (locale-per-field), миграция URL ассетов и разрыв в редакторских воркфлоу, а затем охватывается последовательность: сначала миграция одного ограниченного типа контента, параллельный запуск в обеих системах и сохранение исходной CMS доступной для чтения после того, как она перестала быть доступной для записи.
Почему миграция на Headless CMS — это трансляция схемы, а не перенос контента
Трансляция схемы — это и есть реальная задача. Перенос контента предполагает, что формы с обеих сторон уже совпадают; при миграции на Headless CMS это допущение почти никогда не выполняется само собой, поскольку исходная и целевая модели структурируют контент по-разному на уровне полей, а не только на уровне платформы.
Пост в WordPress — это монолит: заголовок, гибкое тело с богатым текстом, несколько метаполей, шорткоды и встроенные блоки, содержащие структуру, которая корректно отображается только внутри собственных шаблонов WordPress. Contentful, Strapi и Storyblok ожидают структурированный контент: типизированные поля, проверенные форматы и явные поля ссылок, связывающие одну запись с другой, а не ID, зарытый во встроенном шорткоде.
Переход от одного к другому означает переопределение каждого типа контента как более строгой и явной схемы, поле за полем. Документация самой Contentful по моделям контента прямо говорит об этом: тип поля и правила валидации фиксируются на уровне типа контента, и контент, который им не соответствует, отклоняется, а не принудительно преобразуется.
Единицей этой работы по трансляции является ограниченный тип контента, а не весь сайт. Команда берет один тип контента, сопоставляет каждое его поле с целевой схемой и рассматривает несоответствия, потерянные ссылки и языковые конфликты как дефекты трансляции, которые нужно устранить перед переходом к следующему типу.
Контент, смоделированный свободно для традиционной CMS, редко переживает эту трансляцию в неизменном виде. Наше руководство по моделированию контента рассказывает о том, как спроектировать схему с нуля; это руководство объясняет, что происходит, когда существующую схему приходится переносить.
Контрольный список предоперационного аудита перед переходом на целевую платформу
Предоперационный аудит — это структурная инвентаризация того, что исходная модель контента не переживет, а не аудит самого контента. Проведите его до того, как утвердите целевую платформу, поскольку приведенный ниже чек-лист определяет объем работ, а не только риски.
Проведите аудит каждого ограниченного типа контента по отдельности и сравните их с целевой схемой:
- Количество несоответствий типов полей: для каждого поля проверьте, есть ли у целевой системы строгий эквивалент. Гибкое поле богатого текста, принимающее вложенный HTML, встроенные скрипты или произвольные таблицы, не пройдет валидацию против поля структурированного текста Contentful или поля богатого текста Strapi без этапа конвертации.
- Количество потерянных шорткодов: найдите с помощью grep паттерны шорткодов в содержимом тела. WordPress REST API возвращает шорткоды как неразобранную разметку в content.rendered, поэтому каждый шорткод становится задачей ручного сопоставления, а не автоматического.
- Глубина графа ссылок: измерьте, на сколько уровней в глубину уходят внутренние ссылки, встраивания и модули связанных постов. Документация Contentful по связанным записям отмечает, что API доставки контента (Content Delivery API) по умолчанию разрешает ссылки на глубину до 10 уровней; для более глубоких графов требуются явные параметры включения или этап «сплющивания».
- Проверка языковой модели: подтвердите, существуют ли существующие переводы как дубликаты записей или как переопределения на уровне полей. Это определяет выбор между локалью на запись и локалью на поле, и ошибка на этом этапе приведет к необходимости пересборки.
- Инвентаризация URL ассетов: посчитайте абсолютные URL-адреса медиафайлов, уже внедренные в опубликованный контент.
- Разрывы в редакторских воркфлоу: перечислите то, что редакторы делают ежедневно (планирование публикаций, массовое редактирование, ссылки на превью), чего новая платформа не предоставляет «из коробки».
Что ломается при миграции на Headless CMS: несоответствия типов полей
Несоответствия типов полей обычно ломаются первыми при миграции на Headless CMS, поскольку исходная CMS принимала контент, который валидация полей целевой CMS категорически отвергает. Несоответствие не отображается в файле экспорта. Оно проявляется при первой попытке сохранения, часто в виде ошибки 422 или исключения валидации схемы с указанием точного типа ноды, который был отклонен.
Классический пример: гибкое поле богатого текста WordPress, в котором хранятся вложенный HTML, встроенные стили и шорткоды в виде сырой разметки. Укажите это поле для поля богатого текста Contentful, и запись завершится ошибкой, так как поле богатого текста Contentful хранит контент как структурированный документ, проверяемый по фиксированному набору типов нод и разметки, а не произвольный HTML.
Все, что выходит за рамки этой схемы, либо отбрасывается, либо полностью блокирует сохранение. На практике это означает, что тег <span> со встроенными стилями CSS молча теряет свое оформление, шорткод вроде [gallery ids="12,34"] сохраняется как неактивный текст, который никто не отрисовал, а сырой iframe выдает ошибку «неизвестный тип ноды», пока кто-нибудь не удалит его или не пересоберет как встроенную запись.
Конструктор типов контента в Strapi имеет ту же проблему в обратном направлении. Поле, типизированное как короткий текст в источнике, не имеет эквивалента для контента, который на самом деле является богатым текстом, и обратное так же верно для длинных кастомных полей WordPress, которые никогда не проходили валидацию.
Исправление редко представляет собой один этап конвертации. Это три разных исправления в зависимости от того, что сломалось: преобразование HTML в структурированный документ для богатого текста, таблица поиска для сопоставления старых шорткодов с новыми ссылками на компоненты и ручная проверка всего остального, что не прошло оба этапа.
Современные headless-системы ожидают такой дисциплины настройки заранее, а не исправления «на живую» после запуска.
Во время аудита подсчитывайте несоответствия типов полей для каждого ограниченного типа контента, а не по всему сайту: сколько полей имеют прямое совпадение типов, сколько требуют трансформации и сколько не имеют целевого эквивалента и требуют нового поля или решения по данным до начала миграции.
Именно этот показатель, а не количество страниц, определяет реальный объем работ. Правильная оценка также защищает скорость и безопасность в дальнейшем: неразрешенные несоответствия — это как раз тот цифровой долг, который проявляется в виде сломанной верстки или невалидированных данных после запуска новых инструментов.
Моделирование ссылок и связей: Превращение плоских страниц в структурированные ссылки
Моделирование ссылок и связей — это этап, на котором плоская страница WordPress превращается в граф связанных записей, и именно здесь обычно рушится первоначальная оценка объема.
Галерея на шорткодах или блок связанных записей не имеют эквивалента поля в модели безголовного (headless) контента — это клей для презентации, а не данные. Ее пересоздание означает определение того, с каким целевым типом контента соотносится каждый шорткод, а затем связывание их ссылочными полями.
Сложность возрастает с увеличением глубины графа ссылок. Статья, которая подтягивает биографию автора, три связанных поста и карточку продукта, может оказаться на четыре или пять уровней в глубину, как только каждый шорткод превратится в ссылку.
Согласно документации Contentful по API доставки контента (Content Delivery API), параметр include разрешает связанные ссылки на глубину до 10 уровней за один запрос — это запас прочности, который не нужен большинству здоровых моделей контента. Конструктор типов контента в Strapi принудительно преобразует те же связи в явные поля oneToOne, oneToMany или manyToMany — решение о кардинальности связей, которое WordPress никогда не просил команду принимать.
Storyblok разрешает вложенные ссылки во время чтения с помощью параметра разрешения связей, а не хранит их денормализованными, что меняет способ запроса данных фронтендом.
Проведите аудит графа ссылок до фиксации целевой платформы. Подсчитайте среднюю глубину для каждого типа контента и рассматривайте всё, что превышает три или четыре уровня, как кандидата на миграцию в качестве собственного ограниченного типа контента, изолированного от остальной части графа до тех пор, пока он не докажет свою стабильность в новой CMS.
Локализация как решение модели данных: Локаль на запись против локали на поле
Локаль на запись и локаль на поле — это две разные модели контента, а не две настройки одной и той же модели, и выбор неверной стороны для существующего контента вынуждает делать структурную перестройку, а не изменение конфигурации.
Документация Strapi по интернационализации описывает подход «локаль на запись»: каждая локаль получает собственную запись, связанную с локалью по умолчанию через отношение локализации. Таким образом, ссылочные поля указывают на запись конкретной локали, а не на абстрактный контентный элемент, не зависящий от языка.
Contentful придерживается противоположного подхода. В его документации по модели контента и полям локаль рассматривается как свойство поля, а не записи: одна запись хранит французское и английское значения бок о бок, а ссылочное поле указывает на запись один раз с разрешением по локалям во время доставки.
Эти две модели создают разные графы ссылок. Если ваша исходная CMS хранит переводы как отдельные посты, связанные только общим ярлыком (slug) или таблицей плагина, эти данные четко ложатся на модель «локаль на запись» и с трудом — на модель «локаль на поле», где скрипту миграции приходится объединять родственные посты в одну запись, прежде чем даже пытаться выполнить трансляцию схемы.
Ошибочное предположение здесь не проявится в течение нескольких месяцев, пока редактор не попытается добавить локаль, которую модель не может представить, и весь ограниченный тип контента придется перестраивать вокруг другого подхода. Определитесь с этим до миграции хотя бы одного поля, используя руководство по основам моделирования контента, если целевая модель все еще открыта.
Миграция URL ресурсов (ассетов) — это шаг, к которому команды относятся как к формальности, и который разрушает SEO первым. Каждый URL изображения, PDF-файла и видео, уже внедренный в опубликованный контент, должен разрешаться в день запуска, иначе фронтенд отобразит сломанные медиафайлы, и поисковые системы начнут исключать страницу из индекса.
WordPress встраивает медиафайлы в виде абсолютных URL прямо в содержимое поста, согласно документации эндпоинта медиа REST API WordPress: прямой экспорт переносит старые пути, а не новые расположения ресурсов. Contentful, Storyblok и Strapi рехостят ресурсы под новым доменом и идентификатором ресурса (images.ctfassets.net, путь самостоятельно размещенных загрузок или a.storyblok.com соответственно), поэтому каждый встроенный URL из старой CMS теперь никуда не ведет.
Требуется два отдельных исправления, а не одно.
Во-первых, перепишите встроенные URL внутри мигрированного форматированного (rich-text) или структурированного контента на основе карты соответствия старых и новых ID ресурсов, сгенерированной во время миграции — это проход поиска и замены, а не ручное редактирование. Во-вторых, настройте 301 редиректы с каждого старого пути ресурса и страницы на новый эквивалент.
Статус 301 является правильным кодом ответа для постоянного изменения URL, согласно рекомендациям по перенаправлению от Google Search Central, которые сообщают сканерам и браузерам, что старый адрес был навсегда заменен, а не временно перемещен (Google Search Central).
Пропустите карту редиректов, и контент переживет миграцию, а вот URL, по которым поисковые системы уже ранжировали сайт — нет; в этом и заключается разница между миграцией и потерей трафика.
Правильная последовательность действий является частью более широкой дисциплины SEO-безопасной миграции веб-сайтов, где сохранение позиций в выдаче зависит от настройки редиректов не меньше, чем от точности контента.
Редакционный рабочий процесс, который никто не оценил
Неоцененный редакционный рабочий процесс — это тот процесс, который редакторы ежедневно использовали в старой CMS и вообще не могут запустить в новой, и он обычно всплывает в первую неделю после запуска, а не во время тестирования. Традиционные CMS объединяют создание черновиков, предварительный просмотр и публикацию в одном окне без промежуточного API.
Headless CMS разделяет их: контент находится в API управления, рабочий процесс создания черновиков и публикации регулирует то, что обслуживает API доставки, а предварительный просмотр означает запрос неопубликованной записи на фронтенде, который должен быть создан для ее отображения.
Команды, которые мигрируют модель контента и пропускают этот шаг, удивляются, почему редакторы больше не могут просмотреть страницу до ее публикации или почему запланированная публикация, которая работала в WordPress, не имеет эквивалента.
Contentful, Strapi и Storyblok моделируют процесс черновика/публикации по-разному: состояния публикации на уровне записей, пользовательские плагины рабочих процессов и стейджинг на основе источников данных соответственно, поэтому редакционный процесс должен быть перестроен под модель целевой платформы, а не просто перенесен.
Проводите аудит редакционного рабочего процесса до миграции, а не после: перечислите каждое действие, которое редактор совершает между черновиком и публикацией, а затем убедитесь, что каждое из них имеет эквивалент на целевой платформе. Рабочий процесс Storyblok: три этапа (Черновик, Рецензирование, Готово к публикации); Strapi разделяет состояния «Черновик» и «Опубликовано»; Contentful поддерживает одновременное редактирование с откатками и комментариями.
Последовательность и запуск: один ограниченный тип контента, затем параллельный запуск
Спланируйте миграцию на headless CMS, перенеся сначала один ограниченный тип контента, запустив его параллельно с исходной CMS и выполнив переключение только после того, как новая система обслужит продуктовый трафик без необходимости отката. Миграция всего сразу превращает ошибку трансляции схемы в полноценный сбой, а не в локальную проблему.
Тщательно выбирайте ограниченный тип контента. В нем должно быть мало полей со ссылками, отсутствовать сложность с локалями и быть низкий объем редакторского трафика (лучше выбрать лендинг или FAQ, а не модель статьи со встроенными шорткодами и перекрестными ссылками, которая расширяет масштаб на более раннем этапе процесса).
Выполните полную миграцию: контент, медиафайлы и тот редакторский рабочий процесс, который действительно будет использовать контент-команда. Затем оставьте его работающим в целевой CMS, в то время как все остальное остается в традиционной системе.
Это и есть параллельный запуск. Обе платформы обслуживают контент одновременно по разным маршрутам или поддоменам в течение времени, достаточного для выявления того, что пропустило тестирование: проблемы с разрешением ссылок, URL активов с ошибкой 404, откат локалей, который работает не так, как в исходной CMS.
Параллельный запуск длительностью от двух до четырех недель для каждого ограниченного типа контента является стандартной практикой, хотя точная продолжительность определяется объемом редакторской активности для данного типа контента, а не календарной датой.
Критерии переключения должны быть четкими до начала запуска: отсутствие неразрешенных ссылок, доставка медиафайлов, соответствующая производственной производительности, и как минимум один полный редакторский цикл (черновик, ревью, публикация), завершенный контент-командой в новой системе без вмешательства техподдержки.
Сохраните старую CMS доступной для чтения (но не для записи) еще долго после переключения последнего типа контента. Редакторам она понадобится для справок во время следующих этапов миграции, а откат работает только тогда, когда источник истины все еще доступен. Для команд, которые взвешивают, стоит ли этот этап последовательности затрат по сравнению с простым переносом (lift-and-shift), наша работа по разработке headless CMS напрямую затрагивает этот компромисс.
Для команд, которые уже стандартизировались на Contentful, наши услуги по разработке на Contentful подробно описывают, как мы подходим к решению этих задач миграции и моделирования на практике.
В чем заключаются различия механики миграции между платформами: Contentful, Strapi, Storyblok
Contentful, Strapi и Storyblok расходятся в трех аспектах: валидация ссылок, хранение локалей и то, как источники данных или состояния черновиков передаются через их соответствующие API. Это вопрос не рейтинга, а того, где именно ломается мигрированная модель контента.
Contentful проверяет поля со ссылками по фиксированному списку типов контента на уровне схемы, что обеспечивается через Management API при создании или обновлении записей. Поле со ссылкой, созданное для несоответствующего типа контента, сразу же не проходит валидацию, вместо того чтобы корректно деградировать. Поэтому скрипты миграции требуют сопоставления целевой модели контента до запуска импорта, а не после.
Delivery API всегда возвращает только опубликованные записи, а неопубликованные ссылки, перенесенные как черновики, не будут разрешаться ни во что, пока статус публикации не обновится.
Плагин i18n в Strapi рассматривает каждую локаль как отдельную запись, связанную с локалью по умолчанию через отношение localizations. Это модель «локаль на запись», а не «локаль на поле». Контент, созданный в исходной CMS, которая хранит переводы в виде родственных полей в одной записи, требует реструктуризации в отдельные связанные записи. Именно такие решения приводят к необходимости перестройки, если они принимаются после загрузки данных.
Storyblok хранит многоразовые списки опций в виде источников данных (datasources), отдельно от контента историй. Миграция между пространствами означает перемещение историй и источников данных в виде отдельных шагов через Management API. Команды, которые мигрируют только истории, теряют все выпадающие списки и поля выбора, зависевшие от источника данных. Документация по миграции пространств охватывает истории, но для источников данных требуется отдельный проход.
Выбор самой платформы рассматривается отдельно, здесь описана лишь механика переноса в ту систему, которую команда уже выбрала.
WordPress и Drupal в headless: что переносится, а что нет
Контент WordPress и Drupal переживает миграцию на headless CMS в виде «сырых» данных, а не в виде разметки, которая отображает его сейчас. Первым ломается все, что зависит от механизма рендеринга для корректного отображения: шорткоды WordPress и блоки встроенного HTML в Drupal.
Шорткоды WordPress вроде [gallery ids="12,45"] — это вызов функции, который классическая тема разрешает во время рендеринга. У headless-цели нет темы для ее разрешения, поэтому шорткод передается как буквальный текст, если что-то не перепишет его в структурированное поле ссылки до импорта.
Согласно WordPress REST API, содержимое публикации возвращается в виде отрендеренного HTML вместе с исходным полем, но ни то, ни другое не содержит исходные аргументы шорткода в качестве пригодных к использованию данных.
Сопоставление должно происходить выше по потоку, а не во время экспорта.
Drupal структурно чувствует себя лучше: параграфы и поля ссылок на сущности уже моделируют отношения ближе к тому, как ожидает контент Contentful, Strapi и Storyblok. Тем не менее, токены встроенных изображений и представлений в Drupal ломаются точно так же, как и шорткоды. Обе исходные платформы требуют аудита перед миграцией для обнаружения каждого подобного случая до переключения, а не плагина, который обещает справиться с этим автоматически.
Как мигрировать на headless CMS?
Миграция на headless CMS означает отношение к этому процессу как к трансляции схемы, а не как к экспорту контента. Сопоставьте каждое поле источника с целевым полем, заранее отметьте несоответствия типов полей и перенесите один ограниченный тип контента, прежде чем приступать к остальным. Пропуск этапа сопоставления превращает упражнение по планированию в перестройку в середине миграции. Перед тем как браться за эту работу, стоит еще раз взвесить все «за» и «против» перехода на headless, так как усилия по миграции имеют смысл только в том случае, если архитектура по-прежнему подходит вашему современному цифровому стеку.
Сколько времени занимает миграция на headless CMS?
В качестве грубого ориентира закладывайте от двух до четырех недель на каждый тип контента для сопоставления схем, валидации и контроля качества; больше, если задействованы ссылки или многоязычные поля. Один плоский тип контента без локалей может быть перенесен за считанные дни. Глубоко связанная многоязычная модель с дюжиной типов контента может растянуть фазу настройки на несколько месяцев. Сроки зависят от количества типов контента, глубины графа ссылок и от того, требуют ли переработки структуры «локаль на запись» или «локаль на поле», а не только от объема данных. Оцените масштаб аудита перед составлением графика и заложите дополнительное время на проверку безопасности и настройку контроля доступа на новой платформе.
Что ломается при миграции на headless CMS?
Несоответствия типов полей, встроенные шорткоды и конфликты языковых моделей ломаются в первую очередь, за ними следуют URL медиафайлов, зашитые в опубликованный контент, и никем не учтенные редакторские рабочие процессы. Например, разрешительное поле форматированного текста в WordPress не проходит валидацию по сравнению со строгой целевой схемой. Каждый сбой проявляется на разном этапе миграции, поэтому проводите аудит до того, как выберете целевую платформу.
Можно ли мигрировать контент автоматически?
Не совсем так. Инструменты автоматизации быстро выполняют перенос «сырых» полей, но преобразование схемы, моделирование связей и принятие решений о локалях все равно требуют ручного маппинга до запуска любого скрипта. API импорта Contentful, Strapi и Storyblok эффективно перемещают данные только после того, как целевая схема определена, а не до этого. Эти инструменты помогают ускорить рутинные части работы, но они не могут решить, как должна работать ваша модель контента. Рассматривайте автоматизированный импорт как последний шаг в процессе, но никак не первый, особенно при миграции между принципиально разными headless-системами.
Прежде чем писать скрипт миграции
Самая затратная часть миграции headless CMS определяется до перемещения какого-либо контента: какие типы полей не имеют эквивалентов, как сплющиваются связи и соответствует ли подход «локаль для записи» или «локаль для поля» тому, как контент создается на самом деле. Ошибиться в этих трех пунктах означает переделку с нуля, а не исправление.
Если целевая платформа выбрана, но модель контента еще не сопоставлена, именно этот маппинг стоит сделать в первую очередь. Он же подскажет вам, займет ли эта работа две недели или два квартала. Поговорите с нами о вашей модели контента до запуска экспорта.
Если вы все еще решаете, стоит ли вообще переходить, лучшей отправной точкой станет анализ рисков сохранения устаревшей CMS.
