Cloudflare Pages で動かしている Astro サイトは、Astro 7 への更新を慎重に考えた方がよい
このサイトは astro-notion-blog を利用して、Cloudflare でデプロイしている。
ローカルで npm run dev を実行したところ、Astro のバージョンアップを促す警告が表示された。
そこで、いつものように深く考えずに npx @astrojs/upgrade を実行し、依存パッケージを更新した。
その後、再度 npm run dev を実行すると、ローカル環境では問題なくサイトが表示された。
そのため「これなら大丈夫だろう」と思い、Cloudflare へデプロイしたところ、今度はビルドが失敗した。
最初は Node.js のバージョンが古いことが原因だと考え、Cloudflare 側の Node.js を新しいバージョンに変更した。
しかし、それでもデプロイは通らなかった。
ローカルで npm run dev が動いても、Cloudflare 側のデプロイまで成功するとは限らない。Astro 本体、Node.js、Cloudflare アダプター、Pages / Workers の公開経路をまとめて確認する必要がある。
この時点で、Astro 7 への更新は、単に npx @astrojs/upgrade を実行して Node.js を上げれば済む話ではないと分かった。
特に Cloudflare Pages で以前から動かしているサイトでは、Astro 本体だけでなく、Cloudflare への出力形式やデプロイ先の前提も変わっている可能性がある。
Astro 7 が出たので、既存の Astro サイトも「パッケージを上げて、Node.js のバージョンを新しくすれば移行できるだろう」と考えたくなる。
しかし、Cloudflare Pages 上で以前から運用しているサイトの場合、この考え方だけで進めるとデプロイでつまずく可能性が高い。
Astro 本体だけでなく、Cloudflare 向けアダプター、ビルド成果物の配置、Node.js の要件、CI/CD の接続先など、周辺の前提が変わっているためである。
すでに Cloudflare Pages で安定して公開できているサイトなら、軽い気持ちで Astro 7 に上げるのは避けた方がよい。
移行するなら、単なる依存関係の更新ではなく、公開方式そのものの見直しとして扱う必要がある。
何が問題になるのか
Astro 7 以前の構成では、Cloudflare Pages に向けてビルドして、その成果物を Pages 側が拾って公開する、という流れで運用しているケースが多い。
ところが Astro 7 系と新しい Cloudflare アダプターの組み合わせでは、Cloudflare Workers 側を前提にした構成へ寄っている。
つまり、以前と同じ感覚で Pages のビルド設定だけを直しても、期待どおりに公開されないことがある。
Astro、Node.js、Vite、Cloudflare Pages、Workers、Git 連携の設定が重なっているため、どこで失敗しているのかを切り分ける必要がある。
特に困るのは、エラーの原因がひとつに見えない点である。
- Astro 本体の互換性変更
-
@astrojs/cloudflareの出力形式の変化 - Node.js の要求バージョン上昇
- Vite など依存ツール側の追加要件
- Pages と Workers のどちらに公開しているのかという構成差
- Cloudflare 側の Git 連携やビルド設定の残存
このあたりが重なり、単に package.json を更新しただけでは済まない。
Node.js を上げるだけでは解決しない
Astro 7 では、古い Node.js では動かない。
したがって、まず Node.js のバージョンを上げる必要がある。
ただし、ここで注意したいのは「Node.js を新しくしたら終わり」ではないという点である。
Astro 本体の最低要件を満たしていても、内部で使われる Vite などのツールがさらに新しい Node.js の機能を前提にしている場合がある。
そのため、次のような状態になりやすい。
- ローカルでは Node.js を更新してビルドが進む
- Cloudflare Pages 側のビルド環境では古い Node.js が使われる
- CI 上で設定ファイルの読み込みやビルド処理が失敗する
- Node.js を上げても、今度は Cloudflare への出力形式で詰まる
ローカルと Cloudflare 側の Node.js バージョンを揃えたうえで、Astro 7 の出力先やデプロイ方式も確認する必要がある。
つまり、Node.js の更新は必要条件ではあるが、十分条件ではない。
Pages 前提のまま進めると混乱しやすい
既存サイトが Cloudflare Pages で公開されている場合、管理画面上では Pages のプロジェクトが残っており、GitHub への push に反応してビルドが走り続けることがある。
しかし、Astro 7 への移行後に Workers 側へ公開先が変わっていると、Pages のビルドが成功しても本番サイトには反映されない、という分かりにくい状態になる。
管理画面では「ビルド成功」に見えるのに、実際の公開 URL は更新されない。
これは、ビルドしている場所と、実際にユーザーが見ている配信先が一致していないためである。
本番ドメインが Worker 側を向いている場合、Pages 側でビルドが成功していても公開サイトには反映されない。
この状態になると、次のような誤解が起きる。
- main ブランチにマージしたのに本番が変わらない
- Pages のログは成功しているので問題がないように見える
- 手元から
wrangler deployした時だけ更新される - 旧 Pages プロジェクトと新 Worker が同時に存在し、どちらが本番か分からなくなる
Astro 7 への移行では、コードの修正だけでなく「どこにデプロイして、どのドメインがそこを見ているのか」を確認する必要がある。
Astro 側の書き換えも発生する
デプロイ以前に、Astro 本体の変更に合わせた修正も必要になる。
たとえば、古い API や従来の書き方を使っている場合、Astro 7 ではそのまま通らないことがある。
コンテンツ管理、ルーティング、トランジション、Markdown の処理、スタイル周りなど、サイトの作りによって影響範囲は変わる。
静的な小規模サイトなら修正は少なく済むかもしれない。
一方で、以下のような構成では確認項目が増える。
- Cloudflare アダプターを使っている
- SSR を利用している
- Workers や D1 など Cloudflare の別機能と連携している
-
wrangler.tomlが複数ある - API 用 Worker とサイト本体を同じリポジトリで管理している
- Tailwind CSS など周辺パッケージも同時に更新しようとしている
サイトの構成によっては、API の置き換え、ビルド設定、Cloudflare 側の公開方式まで含めた移行作業になる。
このような場合、Astro 7 への更新は「フレームワークのアップデート」ではなく「サイト基盤の移行作業」に近い。
既存の Pages 運用では特に注意したい点
Cloudflare Pages で長く運用しているサイトを Astro 7 に上げる場合、最低限、次の点を確認した方がよい。
1. 現在の本番ドメインが何を向いているか
Cloudflare のルート設定やカスタムドメイン設定を見て、公開ドメインが Pages を見ているのか、Worker を見ているのかを確認する。
ここを曖昧にしたまま作業すると、ビルドは成功しているのに本番に出ない、という状態になりやすい。
2. Git 連携の接続先
GitHub などと連携している場合、push 時に動いているビルドが Pages 側なのか Workers 側なのかを確認する。
古い Pages プロジェクトが残ったままだと、実際には使っていないビルドが動き続け、状況判断を誤る原因になる。
3. Node.js の指定
.node-version や .nvmrc、Cloudflare 側のビルド設定で、実際に使われる Node.js のバージョンを揃える。
ローカルだけ新しくしても、CI 側が古いままでは失敗する。
4. デプロイコマンド
Workers 向けに出力された設定ファイルを使う必要がある場合、wrangler deploy の対象を明示する。
特に、同じリポジトリ内に複数の Cloudflare 用設定がある場合、意図しない Worker を更新してしまう可能性がある。
5. 旧リソースの整理
移行後も Pages プロジェクトや古い Worker が残っていると、後から見たときに構成が分からなくなる。
本番で使わなくなったものは、削除するか、少なくとも Git 連携を止めておいた方がよい。
- 本番ドメインの向き先
- Git 連携が動いている場所
- Cloudflare 側の Node.js バージョン
-
wrangler deployが更新する対象 - 旧 Pages / 旧 Worker の扱い
「とりあえず上げる」は避けた方がよい
Astro 7 への更新は、依存パッケージをまとめて上げるだけで完了するとは限らない。
特に Cloudflare Pages で運用している既存サイトでは、次のような前提で作業した方が安全である。
- 事前に現在のデプロイ経路を図にしておく
- Pages と Workers のどちらで公開するのか決める
- Node.js のバージョンをローカルと CI で合わせる
- 本番ドメインの向き先を確認する
- 旧 Pages プロジェクトを残す場合は役割を明確にする
- 本番反映までを移行作業の完了条件に含める
本番 URL で期待どおりの内容が出ているか、Git への push で自動反映されるか、古いデプロイ経路が残っていないかまで確認する必要がある。
ビルドが通っただけでは移行完了とは言えない。
本番 URL で期待どおりの内容が出ているか、Git への push で自動反映されるか、古いデプロイ経路が残っていないかまで確認する必要がある。
まとめ
Cloudflare Pages で Astro 7 以前の構成を運用している場合、Astro 7 への更新は慎重に進めた方がよい。
Astro 本体の更新、Node.js の更新、Cloudflare アダプターの更新は、それぞれ別の問題を引き起こす可能性がある。
さらに、Pages と Workers の扱いが変わることで、これまでのデプロイ手順がそのまま使えなくなることもある。
すでに Pages で安定運用できているサイトなら、「最新版にしたい」という理由だけで急いで上げる必要はない。
移行する場合は、コード、ビルド環境、Cloudflare の公開先、Git 連携、旧環境の整理まで含めて計画した方がよい。
だからこそ、既存の Pages デプロイ環境では、十分に検証してから進めるべきである。
Astro 7 は単なるバージョンアップではなく、Cloudflare での運用方法を見直すきっかけになる。
だからこそ、既存の Pages デプロイ環境では、十分に検証してから進めるべきである。
参考
