Миграция на 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

1. Новый dev-сервер: dev ≈ prod

Как было в Astro 5.16.5

• dev и prod выполнялись по разным путям кода;
• часть SSR/edge-багов проявлялась только после сборки.

Как стало в Astro 6.0

• dev-сервер построен на Vite Environment API;
• единый runtime для dev и prod;
• корректная локальная разработка для Edge-окружений (Cloudflare Workers).

Практический эффект: меньше ситуаций «локально работает — на проде падает».

---

2. 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.

---

3. CSP (Content Security Policy) — встроенная поддержка

В Astro 5.x

• CSP настраивался вручную;
• inline-скрипты требовали отдельной обработки;
• разные режимы рендеринга — разные решения.

В Astro 6.0

• автоматическая генерация CSP-заголовков или <meta>-тегов;
• автоматические 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: что ломается чаще всего

1. Astro.glob() удалён

❌ Было:

const posts = await Astro.glob('./posts/*.md');

✅ Стало:

const posts = import.meta.glob('./posts/*.md', { eager: true });

⚠️ Важно:

• import.meta.glob() не возвращает Promise;
• поведение отличается — это частая причина ошибок после обновления.

---

2. <ViewTransitions /> переименован

- <ViewTransitions />
+ <ClientRouter />

Переходы между страницами теперь являются частью клиентского роутинга, а не отдельной layout-функцией.

---

3. Legacy Content Collections удалены полностью

Если проект:

• использует старый формат коллекций;
• работал по принципу «пока не сломалось — не трогаем»,

— в Astro 6.0 он не запустится без перехода на Content Layer API.

---

4. CJS-конфигурации больше не поддерживаются

- astro.config.cjs
+ astro.config.mjs

Даже один забытый файл с расширением .cjs — и dev-сервер не запустится.

---

Типичные проблемы при миграции

Из практики:

• ❌ CI падает из-за старой версии Node.js
• ❌ Vite-плагины не совместимы с версией 7
• ❌ Zod 4 ломает схемы в content.config.ts
• ❌ Кастомные SSR-адаптеры требуют переписывания

Это не баги Astro — это плата за чистую архитектуру и отказ от legacy-кода.

---

Как обновляться правильно: пошаговый чек-лист

Подготовка

1. Обновите Node.js до 22.12.0+
2. Проверьте совместимость Vite-плагинов с версией 7
3. Убедитесь, что все конфигурации используют ESM (.mjs)
4. Переведите контент на Content Layer API

Обновление

npx @astrojs/upgrade beta

⚠️ Выполняйте только в отдельной ветке.

После обновления

1. Запустите npm run build и проверьте ошибки
2. Протестируйте все страницы локально
3. Проверьте работу 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 — команда покажет список изменений без их применения.

---

Полезные ссылки

• Официальная документация Astro 6.0
• Руководство по миграции
• Astro на GitHub

---

Если у вас возникли вопросы по миграции или нужна помощь с обновлением проекта — напишите мне.