開発・技術

Astroの静的サイトをCloudflare Workersで公開する最小構成

既存のAstroサイトを静的出力し、Cloudflare WorkersのStatic Assetsで配信する手順。ビルド・配信設定・Git連携・公開確認を分けて整理します。

公開:

Astroで作った小さなブログをCloudflare Workersへ公開するなら、静的なページを出力して、そのフォルダーを配信する構成から始められます。Astroが作る dist と、Wranglerの assets.directory を対応させるのが中心です。

この記事は、既にAstroのプロジェクトがあり、ページを事前に生成できる場合を対象にしています。フォームのAPIや、リクエストごとにページを生成する処理は含めません。Astroの公式ガイドでも、オンデマンドのレンダリングを使う場合にCloudflareアダプターを追加する手順が分けられています。AstroのCloudflare公開ガイド

出力と配信を別々に考える

公開までの流れは、次のようになります。

Astroのページ・記事
    ↓ npm run build
dist内のHTML・CSSなど
    ↓ Wranglerでデプロイ
Cloudflare WorkersのStatic Assets
    ↓
ブラウザーから公開URLへアクセス

Astroが担当するのはファイルの生成、Workersが担当するのは配信です。ビルドが成功しても、Cloudflareへのデプロイや独自ドメインの接続まで終わったとは限りません。

1. Astroを静的出力にする

astro.config.mjs の最小例は次のとおりです。既存のintegrationsや、使用中の設定は必要に応じて残します。

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
});

独自ドメインが決まっているサイトでは、同じ設定に site: 'https://example.jp' のような正式URLを指定します。ただし、site の指定だけでDNSやドメイン接続が設定されるわけではありません。

プロジェクトのフォルダーで依存パッケージを準備し、ビルドを実行します。次の例の npm ci は package-lock.json があるプロジェクト向けです。

npm ci
npm run build

package.json のbuildスクリプトが astro build なら、通常の出力先は dist です。独自に出力先を変更している場合は、次の配信設定もそのフォルダーに合わせます。

2. Wranglerに配信フォルダーを指定する

Wranglerを開発用の依存パッケージとして追加していない場合は、追加します。

npm install --save-dev wrangler

package.json と同じ階層に wrangler.jsonc を置きます。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "example-static-site",
  "compatibility_date": "2026-09-28",
  "assets": {
    "directory": "./dist"
  }
}

name は作成するWorkerの名前に置き換えます。Git連携で作成したWorkerと同じ名前にしてください。compatibility_date は互換性の基準日で、この例では 2026-09-28 を使います。検証した日とは別の値で、使用中のWranglerのローカル実行環境が対応する日付を選びます。Cloudflareの互換日付の説明

静的ファイルを配信するだけなら、この例にはWorkerの実行コードを指定する main は必要ありません。CloudflareのStatic Assetsは、一致する静的ファイルを配信できる構成です。Workers Static Assetsの説明

問い合わせAPIなどを追加したサイトでは、Workerのコードやバインディングも必要になります。その段階の設定を、静的サイトの最小例に最初から全部入れる必要はありません。

3. ローカルで配信を確認する

Astroの開発画面とは別に、ビルドしたファイルをWranglerで確認します。

npm run build
npx wrangler dev --local

表示されたローカルURLで、トップページと既存ページを開きます。存在しないURLの応答も確認してください。この最小設定では、対応するファイルがなく、代わりのWorker処理もなければ404になります。Static Assetsのルーティング

2026年10月7日の確認環境は、Node.js 22.19.0、Astro 7.3.5、Wrangler 4.142.0です。Codexが余白設計のビルド出力を上の最小配信設定でローカル配信し、トップページの200と不存在URLの404を確認しました。今回、新しいクラウド環境へのデプロイは行っていません。

バージョンや出力先が違う場合は、使用しているAstro・Wranglerの公式資料と、プロジェクトのロックファイルも合わせて確認してください。

4. GitHubから自動デプロイする

設定ファイルとロックファイルをGitHubへ反映したうえで、CloudflareのWorkers作成画面でGitリポジトリを接続します。画面上の項目名が変わった場合は、公式のWorkers Builds設定を参照してください。Cloudflareのビルド設定

項目 この最小構成で指定する内容
リポジトリ AstroのプロジェクトがあるGitHubリポジトリ
本番ブランチ 本番へ反映したいブランチ。例:main
ルートディレクトリ package.json と wrangler.jsonc があるフォルダー
ビルドコマンド npm run build
デプロイコマンド npx wrangler deploy

この組合せでは、まずビルドしてから、その出力をデプロイします。npm run deploy にビルド処理も含めているプロジェクトでは、処理を二重に実行していないかスクリプトの内容を確認します。

Cloudflare側のビルド環境で、プロジェクトに対応するNode.jsを使えることも確認してください。手元で成功しても、依存パッケージやNode.jsの条件が違えばクラウド側のビルドが止まることがあります。

5. 成功した段階を確認する

確認する対象を分けると、失敗時に戻る場所が分かりやすくなります。

段階 確認すること
Astroのビルド エラーがなく、指定した出力先にファイルができたか
Wranglerのローカル配信 ページ・CSSが表示され、不存在URLは期待する応答になるか
Cloudflareのデプロイ 対象ブランチ・コミットのデプロイが成功したか
公開URL ブラウザーでHTTPSのページが開き、リンクもたどれるか
独自ドメインを使う場合 ドメイン接続後のHTTPSと、canonical・sitemap等の正式URLが一致するか

初回はCloudflareが割り当てるURLで表示を確認し、その後に独自ドメインを接続すると、コードの問題と接続設定の問題を切り分けやすくなります。

記事を下書きとして管理する場合は、本番用のビルドにその記事が含まれないことも確認します。ローカルの開発画面で読めることと、本番に公開されることは別です。

独自ドメインを取得する場合は、取得費と更新費を分けた費用の考え方で継続費も確認できます。Codexへ実装を依頼する場合の判断や操作の分担は、余白設計を作ったときの記録にまとめています。

← 開発・技術の記事一覧へ