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