本文へ移動
aapp-hacks
← 記事一覧へ
著者
app-hacks
公開日
更新日
確認日

Astro / Cloudflare Pages / Deployment

Astroで作る静的サイトをCloudflare Pagesに最速でデプロイする手順

Astroの静的出力をCloudflare PagesへGit連携で配信し、独自ドメインを割り当てる要点を整理する。

Astroを既定の静的サイトとして使う場合、ビルド結果はHTML、CSS、JavaScriptなどの配信可能なファイルになる。サーバー処理を使わないブログなら、Cloudflare Pagesではアダプターを追加せず、distをそのまま公開する構成が小さい。デプロイ設定の中心は、リポジトリ、ビルドコマンド、出力ディレクトリの三点である。

このサイトで確認した構成

2026年9月11日に、Astro 7.3.2とNode.js 22.22.2でこのリポジトリのnpm run buildを実行した。astro.config.mjsにはsite: 'https://app-hacks.net'とSitemap integrationがあり、outputは指定していないため既定の静的出力を使っている。ビルドでは15ページとdist/sitemap-index.xmlが生成された。Cloudflare Pagesのプロジェクト設定やDNS設定は、このローカル確認には含まれない。

静的出力を確認する

astro.config.mjsでoutput: 'server'を指定していなければ、Astroは既定で静的出力を行う。サイトマップやcanonical URLを正しく作るため、本番URLはsiteへ設定する。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://app-hacks.net',
  integrations: [sitemap()],
});

公開前にはローカルで同じビルドを実行する。

npm ci
npm run build

生成先は既定でdistである。dist/index.html、各ルートのHTML、CSSなどが作られる。distは生成物なのでGitへ含めず、Cloudflare側で毎回ビルドさせる。手元の生成物をコミットすると、ソースと生成物の差分が混在し、どちらが正しいのか判断しにくくなる。

Git連携を設定する

まずGitHubまたはGitLabへプロジェクトをpushする。CloudflareのダッシュボードでWorkers & PagesからPagesプロジェクトを作り、Gitプロバイダーと対象リポジトリを接続する。フレームワークプリセットにAstroがあれば選択し、最終的な値が次の内容になっていることを確認する。

Production branch: main
Build command: npm run build
Build output directory: dist
Root directory: /

モノレポでAstroがサブディレクトリにある場合だけRoot directoryを変更する。単一プロジェクトで不用意にsrcなどを指定すると、package.jsonを見つけられずインストールが失敗する。

Node.jsのバージョンもリポジトリと揃える。現行Astroが要求するバージョンはpackage.jsonのenginesへ記録しておく。

{
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "build": "astro build"
  }
}

Cloudflareのビルド環境が別のNode.jsを選ぶ場合は、ダッシュボードの環境変数など、同サービスが案内する方法でバージョンを合わせる。重要なのは特定の指定手段を固定的に覚えることではなく、ビルドログに表示される実行バージョンとenginesの要求を一致させることである。

Git連携後は、Production branchへのpushが本番デプロイになる。それ以外のブランチやPull Requestにはプレビューデプロイが作られる構成にできる。記事のFrontmatter違反もCloudflare上のnpm run buildで停止するため、壊れたHTMLが途中まで公開されるのではなく、以前の成功済みデプロイが維持される。

デプロイ失敗をログから切り分ける

失敗時は最後のエラー行だけでなく、依存関係のインストール、Node.jsバージョン、Astroのコンテンツ同期の順に確認する。ローカルでnpm installを使い、クラウドでnpm ciが失敗する場合は、package-lock.jsonが更新されていない可能性がある。パッケージを追加したらmanifestとlockfileを同じコミットへ含める。

環境変数が必要な場合、秘密値をリポジトリへ書かない。Cloudflare Pagesの設定へ登録し、Astro側では公開可能な値だけにPUBLIC_接頭辞を使う。静的ビルドでは値が生成物へ埋め込まれることがあるため、APIキーをクライアントコードから参照してはいけない。

カスタムドメインを割り当てる

PagesプロジェクトのCustom domainsから使用するドメインを追加する。対象ドメインのDNSを同じCloudflareアカウントで管理している場合は、必要なレコードが画面の案内に従って構成される。外部DNSを使う場合は、Cloudflareが表示するPagesホスト名へCNAMEを向ける。

wwwのようなサブドメインはCNAMEで扱いやすい。ゾーン頂点のapp-hacks.netを使う場合は、DNS事業者が頂点でのCNAME相当機能を提供するか確認する。Cloudflare DNSではCNAME Flatteningが利用されるため、画面に示された値をそのまま登録する。IPアドレスを推測してAレコードへ固定してはいけない。

本番ホストを決めたら、もう一方のホストをリダイレクト先として統一する。wwwありとなしで同じ内容を別URLとして配信するとcanonicalの扱いが曖昧になる。Astroのsite、各ページのcanonical、robots.txt内のサイトマップURLも、最終的に採用したHTTPSのURLへ揃える。

DNS変更は即時に全利用者へ反映されるとは限らない。Cloudflare側でドメインがActiveになり、TLS証明書が有効になったことを確認してから正式なリンクを案内する。証明書の準備中にHTTPへ戻す設定を加えると構成が複雑になるため、状態が確定するまで待つ方が安全である。

静的Astroサイトのデプロイでは、特別な実行環境を足すより、npm run buildが成功してdistが作られるという契約を保つことが重要である。Git連携、Node.jsバージョン、独自ドメインの正規URLを明示すれば、記事追加から公開までの経路を単純に維持できる。

確認手順と失敗しやすい点

ローカルでは、まずnvm useでリポジトリの.nvmrcに指定されたNode.js 22.22.2へ切り替え、npm run buildを実行する。このサイトではNode.js 20.18.2で同じコマンドを実行した際、Astroが22.12.0以上を要求してビルドを開始しなかった。Cloudflare Pagesでも、ビルドログに出るNode.jsのバージョンがpackage.jsonのenginesと一致するかを確認する。

出力先をsrcなどのソースディレクトリに指定すると、HTMLの公開対象を誤る。静的出力のままならdistを指定し、デプロイ前に生成物内のindex.html、Sitemap、canonical URLを確認する。カスタムドメインのDNSレコードは推測せず、Cloudflareの管理画面が表示する値を使う。

公式資料と関連記事