Миграция на Grav 2.0¶

Grav 2.0 — это смена мажорной версии. Стек сторонних библиотек (Symfony, Twig, Monolog и других) переходит на новое поколение, минимальная версия PHP увеличивается до 8.3, а классическая админка заменена на Admin 2.0, работающую с новым плагином Grav API. Из-за всего этого Grav 2.0 не поставляется как обновление GPM на месте. Вы устанавливаете Grav 2.0 с нуля и импортируете в него существующий сайт.

Эта глава — справочник по этому процессу.

Два пути миграции¶

Есть два поддерживаемых способа перенести сайт с Grav 1.7 или 1.8 на Grav 2.0:

Путь	Когда использовать	Документация
Автоматизированный (через плагин Migrate to Grav 2.0)	Почти всем. Стандартные односайтовые установки, типичный набор плагинов и тем, стандартная структура папок.	Автоматизированная миграция на Grav 2.0
Ручной	Мультисайт, сложные схемы символических ссылок, внешне смонтированные папки `user/`, сайты с собственными плагинами, которые ещё не портированы, и всё остальное, для чего не подходят допущения мастера.	Ручная миграция на Grav 2.0

Оба пути работают одинаково: подготовить свежую установку Grav 2.0 рядом с существующим сайтом 1.x, скопировать контент и конфигурацию, проверить, а затем переключиться. Плагин автоматизирует каждый шаг и добавляет пошагового мастера. Ручной путь выполняет те же шаги вручную, поэтому каждое решение остаётся за вами.

Важно

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

Сводка по пути миграции¶

Grav 1.7.x    →  Grav 1.7.51  →  Grav 2.0 (fresh install + import)
Grav 1.8 beta              →    Grav 2.0 (fresh install + import)

1.7.51 — последний стабильный релиз серии 1.7. Он остаётся поддерживаемым и в обозримом будущем продолжит получать критичные исправления безопасности. Фиксированного срока миграции нет.

Что охватывает миграция¶

Плагин и ручная процедура обрабатывают один и тот же набор входных данных:

Страницы: user/pages/*. Формат контента между 1.7 и 2.0 не изменился, поэтому страницы копируются без преобразования.
Конфигурация: user/config/*. Устаревшие ключи помечаются с предложенными заменами.
Языки: user/languages/*.
Переопределения окружения: user/env/*.
Данные: user/data/* (отправленные формы, данные входа и всё, что плагины здесь хранят).
Учётные записи: user/accounts/*, включая роли и разрешения.
Плагины и темы: обрабатываются через свойство схемы compatibility:. Пакеты с флагом 2.0 заново загружаются из GPM; всё остальное либо пропускается, либо устанавливается отключённым в зависимости от выбранной политики.

Изменение поведения: Twig в контенте¶

Ваши страницы копируются байт в байт, но одно поведение рендеринга в 2.0 изменилось, и именно оно вызывает самый частый вопрос «почему это перестало работать?» после миграции. Если какая-либо из ваших страниц использовала Twig ({{ ... }} или {% ... %}) прямо в Markdown-контенте, этот Twig больше не выполняется по умолчанию.

В Grav 1.7 страница с process.twig: true в метаданных пропускала контент через Twig без ограничений. Поскольку контент страниц может редактировать любой пользователь с доступом к редактированию, это создавало риск внедрения шаблонов на стороне сервера (Server-Side Template Injection). Grav 2.0 закрывает его двумя уровнями: Twig в контенте выключен, пока администратор его не включит, а когда включён, выполняется в песочнице безопасности, которая разрешает только список безопасных тегов, фильтров и функций.

Практический эффект на мигрированном сайте: страница, которая полагалась на Twig в теле, будет показывать необработанную разметку {{ ... }} как обычный текст, пока вы не включите функцию снова. Это касается только контента — файлы .html.twig в вашей теме и плагинах считаются доверенным кодом и никогда не проходят через песочницу, поэтому обычный рендеринг тем и плагинов не затрагивается.

Примечание

Twig в контенте — полное руководство: как включить функцию обратно, как работает песочница и какие альтернативы рекомендуются (шаблоны страниц и шорткоды). После миграции отчёт Инструменты → Отчёты → Twig в контенте в админке перечисляет все страницы, контент которых выводил бы необработанный Twig, чтобы вы могли найти их без ручного поиска. Авторам плагинов и тем также стоит прочитать раздел Песочница Twig в контенте руководства по обновлению для разработчиков.

Для разработчиков плагинов и тем¶

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

Совместимость плагинов: объявление флага compatibility: в blueprints.yaml, чтобы GPM и мастер миграции устанавливали ваш пакет на 2.0.
Интеграция плагинов с API: открытие функциональности плагина через плагин Grav API, чтобы её могли использовать Admin 2.0 и внешние клиенты.
Переводы админки: адаптация languages/*.yaml, чтобы метки и текст справки корректно отображались в Admin 2.0 (включая необязательное пространство имён ICU. для множественных форм и подстановок).

Более глубокий технический справочник по всем изменениям под капотом (требования PHP 8.3, Symfony 7, Twig 3, Monolog 3, удаление классической админки) см. в Руководстве по обновлению для разработчиков.

А о самом портировании кода с 1.x на 2.0 рассказывает страница Разработка с помощью ИИ, где описаны навыки Claude Code, автоматизирующие большую часть шаблонной работы.

Решение проблем¶

Типовые проблемы, конфликты блокировок, восстановление после частичного переключения и правила вывода совместимости при отсутствии флага собраны на странице Решение проблем.

Переходите с другой CMS?¶

Если вы переносите сайт не с существующего Grav, а с другой платформы, раздел Переход на Grav описывает импорт из Drupal 7 и WordPress.