はじめに
このサイト（TAKA-GARAGE）は Astro v6 と Cloudflare Pages で動いている。 構築にあたって予想外にハマった点がいくつかあったので、未来の自分と同じ轍を踏む人のために書いておく。
環境・技術スタック
- Astro v6.x
- @astrojs/cloudflare
- Cloudflare Pages（GitHub 連携）
- Cloudflare D1（SQLite）
ゼロコストを目的とした最適構成 Cloudflare構成を採用することで、2026年4月時点では無料範囲内での運用が可能。 TAKA-GARAGEは静的サイトであること、ブログのような運用を目的としているため、Astroを採用。 また、Cloudflareとの相性も良いため、敢えてNext.jsを活用するメリットが薄い。
開発方法
GeminiCLIを利用したAI駆動開発をした。
大まかな流れは以下の通り。
- プロトタイプ作成
- プロトタイプから仕様書・設計書を作成
- 技術選定
- 実装
- テスト・デプロイ
詰まったポイント
本プロジェクトの開発・デプロイ過程で遭遇した主要な課題とその解決策を記録する。
1. インフラ・設定関連
- 設定ファイルの重複:
wrangler.jsoncとwrangler.tomlの混在による不整合。wrangler.tomlに一本化して解決。 - Cloudflare Pages と Workers の混同: Pages 前提で設定やデプロイを進めていたが、実際には Workers へのデプロイを行っていた。UI 上の見た目の違いで判別に時間がかかり、Gemini の案内と実態が異なっていることに気付いた。
- SESSION KV バインディング:
@astrojs/cloudflare使用時は明示的な利用がなくてもSESSIONバインディングが必須。未設定だとデプロイ後に 404 となる。 - ローカルDBの初期化: リモートDBへの適用だけではローカル環境に反映されない。
npx wrangler d1 executeを--remoteなしで実行してローカルDBを別途セットアップする必要がある。
2. React 19 × Cloudflare Workers 特有の課題
- MessageChannel is not defined: React 19 の SSR が要求する Node.js API が Workers 環境になくデプロイ時にクラッシュ。
- 解決策 (Edge レンダラーへの切り替え):
astro.config.mjsでreact-dom/serverをreact-dom/server.edgeにエイリアス設定。
// astro.config.mjs
vite: {
resolve: {
alias: import.meta.env.PROD
? { "react-dom/server": "react-dom/server.edge" }
: undefined
}
}3. スタイリング・表示関連
- Markdown へのスタイル適用: Astro のスタイルスコープの影響。
<style is:global>を使用して動的コンテンツへのスタイル適用を許可。 - Tailwind v4 の @apply 制約: スタイルブロック内で
@applyを使用する際、@referenceでベースファイルを明示しないとレスポンシブクラスが認識されない。 - SVG ロゴの視認性: 白背景に白ロゴが重なり見えなくなる問題。インライン SVG 化し
fill-currentで色を制御可能にした。 - CSS インポート順序: Tailwind v4 では
@importルールをファイルの最上部に記述する必要がある。
4. データ・実装上の不具合
- JSON パースエラー (Tags): CLI からの
INSERT時にバックスラッシュが混入しJSON.parseが失敗。コンポーネント側でtry-catchと自動リペアロジックを実装。 - 文字化け (Mojibake): ファイル編集過程でのエンコーディング崩れ。全ファイルを UTF-8 でクリーンアップして解消。
5. AI駆動開発特有の課題
- Gemini の承認待ちプロセス: ファイル削除や DB 更新などで Gemini がセーフティチェックを挟むため、承認が完了するまで作業が止まる。作業中に Gemini から離れられず、ワークフローが中断しやすい。
- デバッグと検証の遅延: 修正してもバグが残ることが少なくない。今回は修正後に必ずビルドを通してから目視確認し、デプロイ失敗時はエラーログをもとに原因分析→修正→再デプロイを繰り返すようにした。
まとめ
- Astro + Cloudflare Pages の組み合わせ自体は非常に良い。ゼロコストで SSR + D1 + CDN が使えるのは魅力的だ。特に Astro 6 へのアップデートにより、最新の React 19 も適切に設定（特に Edge レンダラーのエイリアス）を行えば快適に動作する。
- 枯れた技術スタックではないため、破壊的なアップデートが起きる場合は作り直しも視野に入れるべき。
- AI駆動開発はかなり便利な反面、AIでも詰まるバグや業務フロー起因のバグになるとAI主導で解決案を出すことは難しく、LLMの性能向上で改善されるとは考えづらいため、人間によるコントロールはまだまだ必要。