Astro + Cloudflare Pages + microCMS で作る静的サイト構成
はじめに
ウェブサイトを、Astro で構築して Cloudflare Pages にデプロイする構成で実装しました
コンテンツ管理には microCMS を使いつつ、microCMS が未接続の場合はフォールバックデータで動く設計にしたので、その構成を忘れないようにするため、まとめました
Astro とは
Astro は、コンテンツ重視のウェブサイトに特化したフロントエンドフレームワークです
最大の特徴は Islands Architecture（アイランドアーキテクチャ） で、デフォルトでは JavaScript をクライアントに送らず、必要な部分だけインタラクティブにできます
ブログ・コーポレートサイト・ドキュメントサイトなど、静的コンテンツが中心のサイトに向いています
主な特徴：
- ゼロ JS がデフォルト — 静的 HTML として出力するため表示が速い
- フレームワーク非依存 — React・Vue・Svelte などのコンポーネントを混在できる
-
.astroファイル — HTML テンプレートに JS のロジックを書ける独自構文 -
SSG / SSR 両対応 —
output: 'static'で静的生成、output: 'server'でサーバーサイドレンダリング
Cloudflare Pages とは
Cloudflare Pages は、Cloudflare が提供する静的サイトホスティングサービスです
GitHub / GitLab リポジトリと連携し、プッシュするたびに自動でビルド・デプロイが走ります。Cloudflare のグローバル CDN（300 以上の拠点）で配信されるため、世界中どこからでも高速にアクセスできます
主な特徴：
- 無料枠が充実 — 月 500 ビルド・帯域無制限（無料プラン）
- カスタムドメイン + 自動 HTTPS — 独自ドメインの設定と SSL 証明書が無料
- プレビューデプロイ — PR ごとに一意の URL でプレビュー確認できる
- Cloudflare Workers との連携 — エッジでの処理を追加できる
技術スタック
| 役割 | ツール |
|---|---|
| フレームワーク | Astro 4.x |
| ホスティング | Cloudflare Pages |
| CMS | microCMS |
| ビルド出力 | 静的サイト（SSG） |
Astro の設定
astro.config.mjs は最小構成です。
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://example.com',
output: 'static',
integrations: [sitemap()],
});
output: 'static' にすることで、ビルド時に全ページを HTML として出力します。Cloudflare Pages に最適な構成です
@astrojs/sitemap パッケージを入れるだけで sitemap-index.xml が自動生成されます。site を設定しておかないと sitemap の URL が正しく生成されないので忘れずに入れておくといいです
Cloudflare Pages のビルド設定
Cloudflare Pages ダッシュボードのビルド設定はシンプルです
ビルドコマンド: npm run build
出力ディレクトリ: dist
Node.js バージョン: 20
参考用に cloudflare-pages.toml をリポジトリに置いておくと、共有しやすいです
（実際の設定はダッシュボードで行います）
build_command = "npm run build"
build_output_directory = "dist"
[environment.NODE_VERSION]
value = "20"
環境変数の設定
microCMS の API キーはリポジトリに含められないので、Cloudflare Pages ダッシュボードで設定します
設定 > 変数とシークレット
設定する変数：
| 変数名 | 値 |
|---|---|
| MICROCMS_SERVICE_DOMAIN | your-service-domain |
| MICROCMS_API_KEY | your-api-key |
Astro では import.meta.env.MICROCMS_API_KEY でアクセスできます
microCMS クライアントの初期化
import { createClient } from 'microcms-js-sdk';
export const client = createClient({
serviceDomain: import.meta.env.MICROCMS_SERVICE_DOMAIN,
apiKey: import.meta.env.MICROCMS_API_KEY,
});
フォールバックデータパターン
microCMS が未接続（ローカル開発初期や API キー未設定時）でもサイトが動作するよう、try/catch でフォールバックデータを返す設計にしました
export async function getServices(): Promise<Service[]> {
try {
const data = await client.getList<Service>({
endpoint: 'services',
queries: { orders: 'createdAt' },
});
return data.contents;
} catch {
return FALLBACK_SERVICES; // ハードコードされたデータを返す
}
}
これにより：
-
CMS 未設定でも
npm run buildが通る - フロントエンド開発 は CMS なしで始められる
- デプロイ直後 の確認がしやすい
という利点があります
下書きプレビュー対応
開発環境でのみ microCMS の draftKey を付与することで、下書きコンテンツを確認できます。
function withDraft<T extends object>(queries: T) {
return {
...queries,
...(import.meta.env.DEV && import.meta.env.MICROCMS_DRAFT_KEY
? { draftKey: import.meta.env.MICROCMS_DRAFT_KEY }
: {}),
};
}
MICROCMS_DRAFT_KEY は .env ファイルにのみ置き、本番には渡しません。
ディレクトリ構成
src/
├── components/
│ ├── Header.astro
│ └── Footer.astro
├── layouts/
│ └── BaseLayout.astro
├── lib/
│ └── microcms.ts ← CMS クライアント・型定義・取得関数
├── pages/
│ ├── index.astro
│ ├── [slug].astro ← 動的ルーティング
│ └── contact.astro
└── config/
└── office.ts
動的ルーティング [slug].astro では getStaticPaths() を使い、microCMS から全スラッグを取得してビルド時に静的生成します
まとめ
| ポイント | 内容 |
|---|---|
| SSG |
output: 'static' でビルド時に全ページ生成 |
| デプロイ | Cloudflare Pages に npm run build → dist/
|
| 環境変数 | ダッシュボードで設定、import.meta.env でアクセス |
| フォールバック | CMS 未接続時もビルドが通るよう try/catch で対応 |
| 下書き | 開発環境のみ draftKey を付与 |
Astro の静的生成と Cloudflare Pages の相性はとても良く、構成もシンプルに保てました
microCMS との組み合わせもスムーズで、コンテンツ更新のたびに Cloudflare Pages の自動デプロイが走るので助かります