Under the Snow

Astro 5 への実践アップグレード完全ガイド（2025年1月版）

• 2分で読める
Web開発
AstroViteCloudflare PagesContent Layerアップグレード

Astro 5 では、Content Layer の刷新、Server Islands、astro:env の導入、Vite 6 ベース化など、設計の前提が変わるアップデートがまとまりました。本稿は以下の3情報源を踏まえつつ、現場で「どこでハマり、どう回避するか」を具体的にまとめた移行ガイドです。

  • 公式ブログ: Astro 5.0 | Astro（概要とトピック）
  • 公式ドキュメント: Upgrade to Astro v5（破壊的変更・非推奨・既知の問題）
  • 実務系記事（Zenn）: 依存整合・content/config.tsの破壊的変更・テスト落ちの知見

目的は「安全に最短でv5へ上げる」。最後にチェックリストと手順テンプレも付けています。

Astro 5.0 のキービジュアル

Astro 5 の主トピック（要点）

  • Content Layer: コレクションの型安全化とZodスキーマ検証が中核。globローダー時はslug固定値を前提にしない設計へ。
  • Server Islands: 必要箇所だけサーバーレンダリングする島アーキテクチャ。SPA化せず最小限のSSRで拡張が可能。
  • astro:env: 環境変数を安全に扱うAPI。ビルド/実行時の差分を明示できる。
  • Vite 6: ビルド基盤の更新。最適化/ESM解決/プラグインの互換性に影響。
  • 画像系の実験: 画像クロップ、レスポンシブレイアウト、SVG コンポーネント等（段階導入推奨）。

公式アップグレードガイドの読みどころ

  • Upgrade Astro: 本体とインテグレーション/アダプタをメジャー同期で更新。
  • Dependency Upgrades: Vite/TS/プラグインのメジャーを揃える（ラグがあるとビルドが落ちる元）。
  • Deprecated/Removed: 非推奨APIや旧既定が整理。画像・コレクション・SSRフラグなど棚卸し必須。
  • Changed Defaults: プリレンダーやビルドの既定が微変更。暗黙挙動への依存を洗い替え。
  • Breaking Changes: content/config.ts、slugの扱い、scripts処理モードなど。
  • Known Issues: 既知事象を先に確認してから原因切り分け（沼防止）。

現場で起きやすいハマりどころと対策

  1. 依存不整合
  • 症状: 本体だけv5、Vite/TS/プラグインが旧版のままで最適化や型で落ちる。
  • 対策: Astro/Vite/TS/インテグレーションをセットで更新。Lock再生成で解決率UP。
  1. content/config.ts の大変更
  • 症状: 旧サンプルのコピペで型生成エラー。slug前提の実装がリンク切れを誘発。
  • 対策: defineCollection/Zodで再定義。slugは任意とみなし、post.idから拡張子を除去して安定slugを導出するユーティリティに寄せる。
  1. テスト落ち（型/モジュール境界）
  • 症状: TS厳格化やビルドモード差分でユニット/統合テストが不安定。
  • 対策: tsconfigのinclude/exclude見直し、モック更新、HTMLElement等の型注釈＆nullガード徹底。

移行手順テンプレ（安全第一）

  1. 依存更新（同期）
# Astro本体・アダプタ/インテグレーション
pnpm up astro @astrojs/*
# ビルド基盤
pnpm up vite typescript
  1. Content Layerの移行
  • src/content/config.ts をdefineCollection+Zodに更新。
  • slug依存を排し、getPostSlug()のようにpost.slug ?? post.idから拡張子を除去してslug生成を統一。
  • getStaticPaths()/カード/検索APIなど、URL生成箇所で同ユーティリティを使用。
  1. 画像・アダプタ設定
  • Cloudflare Pagesはランタイム最適化（sharp等）が非現実的。adapter cloudflare({ imageService: 'compile' })でビルド時最適化へ。
  • 自作画像ラッパは、文字列URLとImageMetadataの両対応（型エラー回避）。
  1. スクリプトと型の整備
  • 属性付き<script>はis:inlineを明示して挙動固定。
  • DOM操作はHTMLElement/HTMLInputElementで型注釈＋nullガード。イベントはEvent/KeyboardEventを明示。
  1. テスト/型チェック
  • tsconfig.excludeで巨大なJS群を型対象から外す（テスト用ディレクトリなど）。
  • e2eチェック: トップ/記事/カテゴリ/アーカイブ/ページ2の最低動線を実機で確認。

content/config.ts（v5スタイル例）

import { z, defineCollection } from 'astro:content';

const posts = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    publishDate: z.date(),
    category: z.string(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    excerpt: z.string().optional(),
    updateDate: z.date().optional(),
  }),
});

export const collections = { posts };

補助ユーティリティでidからslugを生成し、URLの一貫性を保ちます。

Astro × Cloudflare Pages 運用の勘所

  • 画像: ランタイム最適化は避け、ビルド時処理に統一。
  • 環境変数: astro:envへ移行検討（安全/明示）。
  • Functions/Bindings: 必要なKV等はwrangler/Pages側で確実にバインドし、エラー文言（Invalid binding）で気づきを得る。

チェックリスト（短縮版）

  • 依存（Astro/Vite/TS/インテグレーション）がメジャー同期
  • Lock再生成（rm -rf node_modules && pnpm i）
  • Content Layer：defineCollection+Zod／slugはIDベース生成
  • 画像：CloudflareはimageService: 'compile'
  • スクリプト：is:inline明示・DOM型注釈・nullガード
  • tsconfig：不要ディレクトリをexcludeに
  • e2e：トップ/記事/カテゴリ/アーカイブ/ページ2

まとめ

Astro 5 への移行は、単なるバージョン更新ではなく「型安全なコンテンツ層」や「ビルド基盤刷新」に合わせ、設計の前提を揃える作業です。依存をセットで上げ、slug前提を捨て、Cloudflare向け最適化をビルド時へ寄せる——この3点を押さえれば、多くのトラブルは事前に潰せます。

参考リンク:

  • Astro 5.0 | Astro（公式ブログ）
  • Upgrade to Astro v5（公式アップグレードガイド/日本語）
  • Zenn: Astro 5.x への移行はなかなかハマりどころが多い

関連記事