Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Astro

最終更新 Markdown で表示Agent セットアップ

CLI から始める: Workers 上の Astro プロジェクトのひな形を作り、テンプレートを選びます。

npm create cloudflare@latest -- my-astro-app --framework=astro

すぐデプロイする: Astro で静的ブログを作り、Cloudflare Workers にデプロイします。CI/CD とプレビューもあらかじめ用意されます。

Workers にデプロイ

Astro とは

Astro ↗ は、大量のコンテンツを表示するサイト（ブログ、ドキュメント、オンラインストアなど）向けの JavaScript Web フレームワークです。

Astro は、クライアント側の JavaScript を最小限にして性能を重視します。デフォルトでは、できるだけ多くのコンテンツをビルド時、または「サーバー」（Cloudflare Worker でも可）での オンデマンド ↗ で描画します。インタラクティブさやパーソナライズが必要な箇所にだけ、JavaScript の 「Islands」 ↗ を追加します。

Astro は特定のフレームワークに依存せず、公式の integrations ↗ 経由で React、Preact、Svelte、Vue、SolidJS など主要な UI フレームワークに対応しています。

新しい Astro プロジェクトを Workers にデプロイする

  1. create-cloudflare CLI（C3）で新しいプロジェクトを作成します。

    npm create cloudflare@latest -- my-astro-app --framework=astro

    裏側で行われていること

    このコマンドを実行すると、C3 は新しいプロジェクトディレクトリを作成し、Astro 公式のセットアップツール ↗ を起動し、プロジェクトを Cloudflare 向けに設定します。その後、アプリケーションを Cloudflare へすぐデプロイするかどうかを選べます。

  2. ローカルで開発します。

    プロジェクトを作成したあと、プロジェクトディレクトリで次のコマンドを実行し、ローカル開発サーバーを起動します。

    npm run dev

  3. プロジェクトをデプロイします。

    ローカルマシン、または任意の CI/CD システム（Workers Builds を含む）から、*.workers.dev サブドメイン または カスタムドメイン へデプロイできます。次のコマンドでビルドとデプロイを行います。CI サービスを使う場合は、「デプロイコマンド」 も合わせて更新してください。

    npm run deploy

既存の Astro プロジェクトを Workers にデプロイする

Astro検出済み
生成された設定
wrangler.jsonc
main:dist/_worker.js/index.js
wrangler.jsonc
assets:directory: ./dist, binding: ASSETS
wrangler.jsonc
compatibility_flags:nodejs_compat
wrangler.jsonc
observability:enabled: true
astro.config.mjs
adapter:@astrojs/cloudflare
Workersデプロイ済み
Wrangler が設定を自動で処理します

手動設定

プロジェクトを手動で設定する場合は、次の手順に従います。

静的サイトの場合

Astro プロジェクトがすべて事前描画されている場合は、次の手順に従います。

  1. Wrangler 設定ファイルを追加する

    プロジェクトのルートに、次の内容の Wrangler 設定ファイルを作成します。

    {
	"name": "my-astro-app",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./dist"
	}
}
    name = "my-astro-app"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./dist"

    この設定の役割

    この設定の要点は assets フィールドです。静的アセットの場所を Wrangler に伝えます。ここでは ./dist ディレクトリを指定しています。アセットが別のディレクトリにある場合は、directory の値を合わせて更新します。 ほかの アセット設定オプション も参照してください。

    この設定に main フィールドがない点にも注意してください。静的アセットだけを配信するため、オンデマンドレンダリング / SSR 用の Worker コードは不要です。

  2. プロジェクトをビルドしてデプロイする

    ローカルマシン、または任意の CI/CD システム（Workers Builds を含む）から、*.workers.dev サブドメイン または カスタムドメイン へデプロイできます。次のコマンドでビルドとデプロイを行います。CI サービスを使う場合は、「デプロイコマンド」 も合わせて更新してください。

    npx astro build
    npx wrangler@latest deploy

オンデマンドレンダリングを使うサイトの場合

Astro プロジェクトが オンデマンドレンダリング（SSR とも呼ばれます） ↗ を使う場合は、次の手順に従います。

  1. Astro の Cloudflare アダプターをインストールする

    npx astro add cloudflare

    裏側で行われていること

    このコマンドは、Cloudflare アダプターをインストールし、astro.config.mjs ファイルへ必要な変更を一度に加えます。デフォルトではビルド出力の設定が output: 'server' になり、すべてのページがサーバー側で描画されます。オンデマンドレンダリング / SSR が不要なページ（プライバシーポリシーなどの静的ページ）がある場合は、そのページまたはルートで export const prerender = true を設定し、事前描画します。アダプターの設定オプションは Astro のドキュメント ↗ を参照してください。

  2. .assetsignore ファイルを追加する public/ フォルダに .assetsignore ファイルを作成し、次の行を追加します。

    .assetsignoretxt
    _worker.js
_routes.json

  3. Wrangler 設定ファイルを追加する

    プロジェクトのルートに、次の内容の Wrangler 設定ファイルを作成します。

    {
	"name": "my-astro-app",
	"main": "./dist/_worker.js/index.js",
	// Update to today's date
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"binding": "ASSETS",
		"directory": "./dist"
	},
	"observability": {
		"enabled": true
	}
}
    name = "my-astro-app"
main = "./dist/_worker.js/index.js"
# Set this to today's date
compatibility_date = "2026-09-20"
compatibility_flags = [ "nodejs_compat" ]

[assets]
binding = "ASSETS"
directory = "./dist"

[observability]
enabled = true

    この設定の役割

    この設定の要点は次のとおりです。

    • main は Worker スクリプトのエントリポイントを指します。Astro アダプターが生成し、サーバー描画のページを動かします。
    • assets.directory は静的アセットの場所を Wrangler に伝えます。ここでは ./dist ディレクトリを指定しています。アセットが別のディレクトリにある場合は、directory の値を合わせて更新します。

    Wrangler の設定オプション と アセット設定オプション も参照してください。

  4. プロジェクトをビルドしてデプロイする

    ローカルマシン、または任意の CI/CD システム（Workers Builds を含む）から、*.workers.dev サブドメイン または カスタムドメイン へデプロイできます。次のコマンドでビルドとデプロイを行います。CI サービスを使う場合は、「デプロイコマンド」 も合わせて更新してください。

    npx astro build
    npx wrangler@latest deploy

バインディング

バインディングを使うと、Astro アプリケーションを Cloudflare Developer Platform と統合でき、コンピュート、ストレージ、AI などへアクセスできます。利用できるものと設定方法は、バインディングの概要 を参照してください。

Astro のドキュメント ↗ では、locals からのアクセス方法を説明しています。

セッション

Astro の Sessions API ↗ を使うと、ユーザー設定、ショッピングカート、認証情報など、リクエストをまたぐユーザーデータを保存できます。Cloudflare アダプターを使うと、Astro はセッションストレージに Workers KV を自動設定します。

デプロイ時、Wrangler は SESSION という名前の KV 名前空間を自動で用意するため、手動設定は不要です。

---
export const prerender = false;
const cart = await Astro.session?.get("cart");
---

<a href="/checkout">{cart?.length ?? 0} items</a>

別のバインディング名を使いたい場合は、アダプターの sessionKVBindingName ↗ オプションで KV バインディング名を変更できます。

カスタム 404 ページ

Astro サイトでカスタム 404 ページを配信するには、Wrangler 設定に not_found_handling を追加します。

{
	"assets": {
		"directory": "./dist",
		"not_found_handling": "404-page"
	}
}
[assets]
directory = "./dist"
not_found_handling = "404-page"

ルートが見つからないとき、Cloudflare はカスタム 404 ページ（例: src/pages/404.astro）を返します。詳細は 静的アセットのルーティング動作 を参照してください。

Astro のビルド設定

Astro の Cloudflare アダプターは、ビルド出力の設定を output: 'server' にします。すべてのページが Cloudflare Worker でオンデマンド描画されます。オンデマンドレンダリング / SSR が不要なページ（プライバシーポリシーなどの静的ページ）がある場合は、そのページまたはルートで export const prerender = true を設定し、事前描画します。オンデマンドレンダリングの詳細は Astro のドキュメント ↗ を参照してください。

Astro を静的サイトジェネレーターとして使う場合、Astro の Cloudflare アダプターは不要です。Astro はデフォルトでビルド時にすべてのページを事前描画するので、その静的アセットを Cloudflare へアップロードして配信できます。

Node.js の要件

Astro 5.x は Node.js 18.20.8、Node.js 20.3.0 以降の 20.x、または Node.js 22.0.0 以降に対応しています。Astro 6.x と 7.x は Node.js 22.12.0 以降が必要です。Workers Builds を使う場合、デフォルトの Node.js バージョンはこの要件を満たします。デフォルトを上書きする場合は、Astro の Node.js 要件 ↗ を満たすバージョンを選びます。

役に立ちましたか？