Astro 6 へのアップグレードを試みて断念した話

32 閲覧

どうも、コディです。

このサイトを Astro 5 から Astro 6 にアップグレードしようとして、結局 Astro 5 に戻した 話です。

Astro 6 の主な変更点

  • Vite 7 へのアップグレード
  • Zod 4 へのアップグレード（z のインポート元が変更）
  • Shiki 4 へのアップグレード
  • レガシー Content Collections API の完全削除
  • ViewTransitions → ClientRouter へのリネーム
  • Astro.glob() の削除

詳しくは 公式マイグレーションガイド を参照してください。

やったこと

1. semver 範囲内の更新を先にデプロイ

いきなりメジャーアップグレードするのではなく、まずは既存のバージョン範囲内で安全にアップデートしました。

astro            5.16.13 → 5.18.1
wrangler         4.60.0  → 4.72.0
@astrojs/rss     4.0.15  → 4.0.17
@astrojs/sitemap 3.7.0   → 3.7.1

これで問題なくデプロイできることを確認してから、次のステップに進みました。

2. Astro 6 へのアップグレード

pnpm dlx @astrojs/upgrade で一括アップグレード。

astro                5.18.1  → 6.0.2
@astrojs/cloudflare  12.6.13 → 13.0.2
@astrojs/mdx         4.3.14  → 5.0.0

コードの修正は z のインポート元変更（astro:content → astro/zod）だけで、ローカルビルドはすんなり通りました。

3. Cloudflare Pages で 404

ところが、Cloudflare Pages にデプロイすると サイト全体が 404 に。

原因は @astrojs/cloudflare 13 のビルド出力構造が変わったことでした。v12 では dist/ 直下に _worker.js と静的ファイルが配置されていましたが、v13 では dist/client/（静的ファイル）と dist/server/（ワーカー）に分離されています。

Cloudflare Pages がこの新構造を認識するには wrangler.toml に pages_build_output_dir を設定する必要がありますが、これを追加するとビルド時に ASSETS バインディング名の競合エラーが発生します。

The name 'ASSETS' is reserved in Pages projects.
Please use a different name for your Assets binding.

@astrojs/cloudflare 13 が生成するプリレンダーワーカーの設定で ASSETS バインディングを使っており、Pages の予約名と衝突するというバグのようです。

結論

Astro 6 自体のマイグレーションは簡単でしたが、Cloudflare Pages との組み合わせに現時点では互換性の問題があるため、Astro 5 に戻しました。

@astrojs/cloudflare アダプター側の修正を待って、改めてアップグレードを試みる予定です。

今日も読んでくれてありがとう。