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

Типовые проблемы, возникающие при миграции с Grav 1.x на 2.0, и способы их решения.

«Версия PHP слишком низкая»¶

Мастер отказывается продолжать, если не находит PHP 8.3 или новее.

Grav 2.0 требует как минимум PHP 8.3. Если ваш хост предлагает только более старые версии, миграция пока невозможна. Большинство хостингов с общим доступом позволяют выбирать версию PHP для домена в панели управления. Переключитесь там на 8.3 или новее и запустите мастер заново.

Если на сервере доступно несколько бинарников PHP (например, php — это 8.1, но существует php8.3), укажите путь явно при запуске CLI:

php8.3 bin/plugin migrate-grav init

Плагин помечен как несовместимый¶

Мастер проверяет флаг совместимости compatibility: в схеме каждого установленного плагина на наличие 2.0. Плагин считается несовместимым, если в нём указан только 1.7 или если флага нет, а в dependencies: объявлен grav >= 1.7.

У вас три варианта:

1. Пропустите его. Если плагин больше не используется, это правильный ответ. Выберите политику skip в мастере или просто не копируйте его при ручной миграции.
2. Отключите его. Если вы хотите оставить файлы на месте в ожидании версии 2.0 от автора, выберите политику disable. Папка плагина сохраняется в подготовленной копии, но запись конфигурации устанавливает enabled: false.
3. Всё равно проверьте его. Если у вас есть основания полагать, что плагин на самом деле работает на 2.0 (например, вы проверили его сами), переключите режим совместимости мастера на Permissive. Плагины, совместимость которых определяется по зависимостям, тогда переводятся в «совместимые». Плагины, явно помеченные несовместимыми, по-прежнему блокируются.

О собственных или приватных плагинах, которые вы поддерживаете сами, см. страницу Разработка с помощью ИИ — там описан самый быстрый путь их портирования.

«Я не узнаю этот плагин в списке совместимост軶

Мастер сканирует установленные плагины на действующем сайте, и иногда среди них обнаруживаются пакеты, которые вы не помните, как устанавливали. Отнеситесь к миграции как к возможности для уборки: используйте политику skip для всего, что вы активно не используете.

Подготовленный сайт возвращает 404 или циклы перенаправлений¶

Чаще всего это вызвано тем, что рабочий .htaccess (или конфигурация nginx) перенаправляет запросы к /grav-2/ обратно в действующую установку.

Apache. Добавьте правило в начало рабочего .htaccess, чтобы обойти перезапись для пути подготовленной копии:

RewriteRule ^grav-2/ - [L]

Мастер migrate-grav добавляет этот маркер автоматически. При ручной миграции добавьте его вручную.

Nginx. Добавьте блок location перед существующей директивой try_files:

location ^~ /grav-2/ {
    try_files $uri $uri/ /grav-2/index.php?$query_string;
}

Не удаётся войти в админку на подготовленном сайте¶

Две частые причины:

1. Несовпадение версий PHP на подготовленной копии и действующем сайте. Сессии и хеши паролей переносимы, но убедитесь, что при тестировании используются совместимые версии PHP. Если действующий сайт работает на PHP 8.1, а подготовленный — на 8.3, войдите на подготовленном сайте заново, а не рассчитывайте, что существующая сессионная cookie перенесётся.
2. Двухфакторные коды. Если у вас включена 2FA, нужен доступ к приложению-аутентификатору: секрет переносится вместе с файлом учётной записи, а активное окно TOTP — нет.

Восстановление после неудачного переключения¶

Шаг переключения — единственный момент, когда мастер изменяет действующий webroot. Он выполняется в три фазы:

1. Zip-архив резервной копии. Каждый файл в действующей установке 1.x (кроме подготовленной grav-2/) упаковывается в grav-2/backup/migration-backup-<version>--<timestamp>.zip. После переключения архив оказывается в backup/<…>.zip рядом с другими резервными копиями Grav.
2. Удаление. Элементы верхнего уровня в webroot удаляются.
3. Переключение. Содержимое grav-2/ перемещается в webroot.

Если фаза 2 или 3 прерывается на середине, действующий webroot может быть частично разрушен. Zip-архив резервной копии из фазы 1 — ваш инструмент восстановления.

Определите блокировку¶

Самая частая причина сбоя (особенно в Windows, где открытые файлы нельзя удалить) — процесс, удерживающий дескриптор файла внутри webroot: редактор кода с открытым .git/index, tail, читающий файл журнала, или графический клиент git, сканирующий .git/objects/. Мастер сообщает конкретный путь, на котором произошёл сбой. Закройте всё, что держит файл открытым, и повторите попытку.

Восстановите из zip-архива резервной копии¶

Резервная копия миграции — обычный zip-архив. Распакуйте его обратно поверх webroot:

• Windows. В Проводнике щёлкните правой кнопкой по архиву → Извлечь всё… и выберите webroot. Мастер извлечения правильно восстанавливает дерево каталогов. 7-Zip и WinRAR тоже подойдут.
• macOS. Дважды щёлкните архив в Finder или выполните unzip migration-backup-*.zip -d /path/to/webroot в Терминале.
• Linux. unzip migration-backup-*.zip -d /path/to/webroot.

После восстановления webroot очистите состояние мастера и запустите его заново:

• Удалите .migrating в webroot
• Удалите подготовленную папку grav-2/
• Удалите tmp/grav-2.0-staged.zip

«Zip-архив распаковывается плоскими файлами с · или \ в именах»¶

Если мастер работал в Windows с версией до 1.0.0-rc.3, в zip-архиве резервной копии есть ошибка разделителей: имена записей используют \ вместо /. Любой распаковщик, следующий стандартам, считает обратные слэши обычными символами имени файла и вываливает все файлы в корень архива с именами вроде user\plugins\admin\file.php.

Плагин migrate-grav поставляется со скриптом восстановления user/plugins/migrate-grav/wizard/mg-repair-backup.php. Скопируйте его куда угодно и запустите:

php mg-repair-backup.php migration-backup-1.7.x--20260507111032.zip

Он запишет migration-backup-1.7.x--20260507111032.fixed.zip рядом с оригиналом, нормализовав все имена записей к прямым слэшам. Распакуйте исправленный архив любым инструментом — дерево каталогов будет правильным.

Скрипт самодостаточен: не нужны ни Grav, ни Composer, ни контекст плагина. Требуется PHP 8.1+ с расширением zip. Архивы резервных копий, созданные rc.3 и новее, не затронуты.

Устаревшие ключи конфигурации¶

Небольшое число ключей system.yaml в Grav 2.0 переименовано или удалено. Мастер помечает их на шаге импорта контента с предложенными заменами. При ручной миграции просмотрите user/config/system.yaml после копирования и сверьте его с примечаниями к выпуску Grav 2.0.

Тема отображается неправильно¶

Если для вашей активной темы нет релиза, совместимого с 2.0, у вас два варианта:

1. Переключитесь на Quark 2 — новую тему по умолчанию, поставляемую с Grav 2.0. Страницы будут отображаться с настройками Quark 2 по умолчанию, пока вы не настроите тему.
2. Портируйте тему. Структура темы заметно не изменилась; самые частые проблемы — синтаксис Twig, устаревший в старых версиях и теперь удалённый, ссылки на ресурсы, зависевшие от вывода классической админки, и ошибки типов PHP в файлах .php темы при новой минимальной версии PHP. Навыки из раздела Разработка с помощью ИИ охватывают портирование плагинов; те же шаблоны применимы и к темам.

Twig в контенте страницы отображается как обычный текст¶

После миграции страница, которая раньше рендерила {{ ... }} или {% ... %} из тела Markdown, теперь показывает эту разметку как обычный текст. Это ожидаемо: Grav 2.0 по умолчанию отключает Twig в контенте как меру безопасности (защита от внедрения шаблонов на стороне сервера), а при повторном включении выполняет его в песочнице, которая разрешает только известный безопасный набор членов Twig.

Чтобы найти и исправить затронутые страницы:

1. Откройте Инструменты → Отчёты → Twig в контенте в админке. Там перечислены все страницы, контент которых выводил бы необработанный Twig, с понятным объяснением и ссылкой на редактор страницы.
2. Если фича действительно нужна, включите её в разделе Конфигурация → Безопасность (или установите twig_content.process_enabled: true в user/config/security.yaml) и очистите кэш командой bin/grav cache.
3. Если после включения конкретное выражение всё равно выводится необработанным, его заблокировала песочница. Отчёт и logs/security.log называют точный тег, фильтр, функцию, метод или свойство, а в отчёте есть кнопка Добавить в список разрешённых.

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

Я хочу начать заново¶

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

• .migrating в webroot
• Подготовленную папку grav-2/
• tmp/grav-2.0-staged.zip

После шага переключения «начать заново» означает восстановить zip-архив резервной копии миграции и запустить мастер повторно.

Сообщение о проблемах¶

Если вы столкнулись с проблемой миграции, которой нет на этой странице:

• Создайте issue в репозитории migrate-grav, приложив содержимое .migrating и соответствующие записи из logs/grav.log.
• Или спросите в канале #migration в Discord Grav.