Миграция на Astro 6.0 с версии 5.16.5: что изменилось и как обновиться
Astro 6.0 — это не просто очередной релиз, а архитектурная точка невозврата.
Фреймворк окончательно уходит от гибридной магии и приходит к предсказуемому runtime-поведению.
Если вы работаете на Astro 5.16.5 и думаете, стоит ли обновляться — эта статья сэкономит вам несколько вечеров отладки и поможет избежать типичных ошибок при миграции.
Что важно понять перед обновлением
Astro 6.0 — это осознанная миграция, а не просто npm update.
Причины:
- жёсткое требование к версии Node.js;
- обновление базовых зависимостей (Vite 7, Zod 4);
- удаление legacy-API;
- изменения в dev-сервере и роутинге.
Технические требования Astro 6.0
| Компонент | Требование |
| ------------ | ----------------------------------------------- |
| Node.js | 22.12.0+ (версии 18 и 20 больше не поддерживаются) |
| Vite | 7.0 |
| Zod | 4.x |
| Конфигурации | Только ESM (файлы .mjs) |
⚠️ Если в проекте используется CI/CD, Docker или VPS на старой версии Node — обновление начнётся именно с этого.
Ключевые изменения Astro 6.0
- Новый dev-сервер: dev ≈ prod
Как было в Astro 5.16.5
- dev и prod выполнялись по разным путям кода;
- часть SSR/edge-багов проявлялась только после сборки.
Как стало в Astro 6.0
- dev-сервер построен на Vite Environment API;
- единый runtime для dev и prod;
- корректная локальная разработка для Edge-окружений (Cloudflare Workers).
Практический эффект:
меньше ситуаций «локально работает — на проде падает».
- Live Content Collections (stable)
Это одна из самых полезных функций Astro 6.0.
Если требуется:
- обновлять данные без пересборки;
- хранить их рядом с контентом;
- не создавать дополнительный API-слой,
— это именно то, что нужно.
Пример: live-данные без пересборки
// src/content/config.ts
import { defineCollection } from 'astro:content';
export const collections = {
inventory: defineCollection({
type: 'live',
loader: async () => {
const res = await fetch('https://api.example.com/inventory');
return res.json();
},
}),
};
Использование на странице:
---
import { getCollection } from 'astro:content';
const inventory = await getCollection('inventory');
---
<ul>
{inventory.map(item => (
<li>{item.name} — {item.price} ₽</li>
))}
</ul>
Где это полезно на практике:
- динамические цены;
- наличие товаров;
- статусы заказов;
- данные из внешних сервисов;
- feature flags.
- CSP (Content Security Policy) — встроенная поддержка
В Astro 5.x
- CSP настраивался вручную;
- inline-скрипты требовали отдельной обработки;
- разные режимы рендеринга — разные решения.
В Astro 6.0
- автоматическая генерация CSP-заголовков или -тегов;
- автоматические hash-суммы для:
- inline-скриптов;
- inline-стилей;
- динамических чанков;
- одинаково работает в SSG / SSR / SPA.
Пример конфигурации:
// astro.config.mjs
export default {
security: {
contentSecurityPolicy: {
directives: {
'default-src': ["'self'"],
'script-src': ["'self'"],
'style-src': ["'self'"],
},
},
},
};
Это уровень безопасности, который раньше требовал настройки Nginx и ручного управления хешами.
Breaking changes: что ломается чаще всего
- Astro.glob() удалён
❌ Было:
const posts = await Astro.glob('./posts/\*.md');
✅ Стало:
const posts = import.meta.glob('./posts/\*.md', { eager: true });
⚠️ Важно:
- import.meta.glob() не возвращает Promise;
- поведение отличается — это частая причина ошибок после обновления.
- переименован
- <ViewTransitions />
+ <ClientRouter />
Переходы между страницами теперь являются частью клиентского роутинга, а не отдельной layout-функцией.
- Legacy Content Collections удалены полностью
Если проект:
- использует старый формат коллекций;
- работал по принципу «пока не сломалось — не трогаем»,
— в Astro 6.0 он не запустится без перехода на Content Layer API.
- CJS-конфигурации больше не поддерживаются
- astro.config.cjs
+ astro.config.mjs
Даже один забытый файл с расширением .cjs — и dev-сервер не запустится.
Типичные проблемы при миграции
Из практики:
- ❌ CI падает из-за старой версии Node.js
- ❌ Vite-плагины не совместимы с версией 7
- ❌ Zod 4 ломает схемы в content.config.ts
- ❌ Кастомные SSR-адаптеры требуют переписывания
Это не баги Astro — это плата за чистую архитектуру и отказ от legacy-кода.
Как обновляться правильно: пошаговый чек-лист
Подготовка
- Обновите Node.js до 22.12.0+
- Проверьте совместимость Vite-плагинов с версией 7
- Убедитесь, что все конфигурации используют ESM (.mjs)
- Переведите контент на Content Layer API
Обновление
npx @astrojs/upgrade beta
⚠️ Выполняйте только в отдельной ветке.
После обновления
- Запустите npm run build и проверьте ошибки
- Протестируйте все страницы локально
- Проверьте работу SSR/SSG в зависимости от режима
Когда стоит обновляться
✅ Обновляйтесь сейчас, если:
- это новый проект;
- используете Edge / Cloudflare Workers;
- нужны live-данные без пересборки;
- проект рассчитан на поддержку в 2026 году и далее.
❌ Отложите обновление, если:
- проект стабилен и приносит доход;
- много кастомных интеграций и плагинов;
- нет времени на полноценное регрессионное тестирование.
Вывод
Astro 6.0 — это:
- меньше магии и неявного поведения;
- больше предсказуемости;
- единый runtime для разработки и продакшена;
- зрелая архитектура фреймворка.
Astro 5.16.5 остаётся отличной стабильной версией.
Astro 6.0 — версия для проектов, которые будут развиваться в будущем.
Часто задаваемые вопросы
Можно ли обновиться напрямую с Astro 4.x до 6.0?
Технически возможно, но рекомендуется сначала обновиться до последней версии 5.x, проверить работоспособность, а затем переходить на 6.0.
Что делать, если Vite-плагин не поддерживает версию 7?
Проверьте репозиторий плагина на наличие обновлений или beta-версий. Если обновления нет — временно откажитесь от плагина или найдите альтернативу.
Как проверить, что проект готов к миграции?
Запустите npx @astrojs/upgrade beta --dry-run — команда покажет список изменений без их применения.
Полезные ссылки
Если у вас возникли вопросы по миграции или нужна помощь с обновлением проекта — напишите мне.
Top comments (0)