Webサイトホスティングで使うCloudflare Workers | 第2回 AstroのサイトをWorkersにデプロイする

無料公開中

公開翌日4時まで

Webサイトホスティングで使うCloudflare Workers 第2回 AstroのサイトをWorkersにデプロイする

第2回は、Astroで作ったサイトをCloudflare Workersにデプロイします。Wranglerを使った手元からのデプロイと、SSRのためのアダプターの設定、そしてGitHubリポジトリと連携した自動デプロイとプレビューURLの生成までを解説します。

カテゴリー: Webサービス >; Cloudflare Workers

2026年8月27日発行

著者渡辺由フロントエンド・エンジニア

Webサイトホスティングで使うCloudflare Workers シリーズの記事一覧

前回まで

前回は、PagesとWorkersの違いや、Workersでは何ができるのか、といった全体像をお話ししました。

今回は、実際にAstroで作ったサイトをWorkersにデプロイします。さらにSSGあるいはSSRを含むサイトを手元からデプロイした後は、さらにGitHubリポジトリと連携させて「pushしたら自動でデプロイされ、作業ブランチのプルリクエストにはプレビューURLが出る」という状態に整えます。

なお、この記事で作っていくAstroプロジェクトを、次のリポジトリで公開しているので、併せて参考にしてください。

デモリポジトリ

記事の手順ごとにコミットを分けているので、どのファイルがどの段階で変わったのかを確認できます。

codegrid/2026-workers-hosting-astro

Astroの準備

まずはAstroのプロジェクトを作ります。

Astroプロジェクトの作成

npm create astro@latest

作成するプロジェクトは「A basic, helpful starter project」を選択すればよいでしょう。また、「Initialize a new git repository?」も yes にしてください。後ほどGitHubとCloudflare Workersを接続します。

この記事では、最新のバージョン7をインストールして進めますが、6系でも問題ありません。

古いバージョンのAstro

Astro 5以前のバージョンをCloudflare Workersにデプロイすることも可能ではあります。特にSSGのみのサイトに関してはバージョン6や7とさほど違いはありません。

SSRを使う場合は、後述のアダプターと呼ばれるライブラリがCloudflare Pagesを前提にしたものになってしまい、Workersで使おうとすると、不要なファイルが書き出されてしまったり、設定ファイルの記述や環境変数の扱いに一手間必要になったりします。

WorkersでAstroを使うのであれば、基本的にはバージョン6以降がよいでしょう。

SSGの場合

さて、先ほどインストールした「A basic…」テンプレートのAstroプロジェクトは、ルートの1ページしかなく、SSGしか使っていません。まずはこの、SSRを使わない状態でCloudflare Workersにデプロイしてみましょう。

まず、Cloudflare公式のCLIツールであるWranglerをインストールします。このツールを使ってサイトをデプロイできます。Wrangler自体は、Cloudflareのさまざまなサービス（Workersだけでなく、データベースやストレージなども含みます）に対してターミナルから操作するためのツールです。

Wranglerのインストール

npm i -D wrangler

続いて、このWranglerが読み取る設定ファイルであるwrangler.jsoncを用意します。Astroプロジェクトのルートディレクトリに配置し、Gitの管理下に含めてかまいません。

SSGのみの場合のwrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json", // このファイルのスキーマを宣言
  "name": "demo-astro-workers", // Workersの名前（任意）
  "compatibility_date": "2026-08-13", // workerdランタイムに関する指定（後述）
  "assets": {
    "directory": "./dist", // 静的に配信するディレクトリ
  }
}

AstroはデフォルトでdistディレクトリにビルドしたHTMLを出力しますので、そのディレクトリを静的アセットとして指定しています。

補足：assetsに指定できるもの

directory以外にも、not_found_handlingやhtml_handlingなどのキーがあり、404や末尾のスラッシュの扱いについての指定も可能です。

wrangler.jsoncが用意できたらデプロイしてみましょう。まずnpm run buildでAstroプロジェクトをビルドした後、npx wrangler loginでCloudflareアカウントにログインします。これでWranglerに権限が付与されます。

そしてnpx wrangler deployを実行してみてください。index.htmlなどのファイルがアップロードされ、✨ Success! Uploaded 5 files (1.03 sec)のように表示されればデプロイ完了です。

Cloudflareのダッシュボードでも確認できます。左メニューの「コンピュート」→「Workers & Pages」を選ぶと、Workers/Pagesの一覧の中に、先ほどnameに記述した「demo-astro-workers」という名前のWorkersアプリケーションができているはずです。すでにデプロイされているので、右上の「訪問する」ボタンからアクセス可能です。

SSRを使う場合

続いて、SSRも行うAstroプロジェクトの場合です。まずはアダプターと呼ばれるライブラリを追加します。このアダプターがWorkersのランタイム上でのレンダリング処理を担ってくれるわけです。

アダプターの追加

npx astro add cloudflare

このように実行すると、@astrojs/cloudflareというnpmパッケージがインストールされ、astro.config.mjsにアダプターの設定が追記されます。

アダプターの設定（astro.config.mjs）

// @ts-check
import { defineConfig } from 'astro/config';

import cloudflare from '@astrojs/cloudflare';

// https://astro.build/config
export default defineConfig({
  adapter: cloudflare()
});

エントリーポイントの設定

wrangler.jsoncにも追加の記述が必要です。具体的には、mainというキーに@astrojs/cloudflare/entrypoints/serverを指定します。また、assetsキーにbindingを、compatibility_flagsにnodejs_compatを追加し、次のように指定します。

SSRを含む場合のwrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "demo-astro-workers",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2026-08-13",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS"
  }
}

前回、「アダプターがworkerd上で動くコードを生成する」とお話ししました。それが表れているのがmainの行です。ここにはWorkerとして実行されるコードのパスを書くのですが、SSRで実行したいのはWebページをレンダリングするコードです。そのコードはアダプターが生成してくれます。@astrojs/cloudflareは@astrojs/cloudflare/entrypoints/serverにコードを生成するので、mainにその値を指定しているというわけです。

そしてassetsは先ほどのままdistディレクトリが指定されています。仮に全ページSSRだったとしても、faviconや画像などの静的リソースも存在するでしょうから、ここは変わりません。

"binding": "ASSETS"は少々ややこしいのですが、アダプターがレンダリング処理を実行する際にdistディレクトリ内のファイルを参照できるようにするための記述です。必要ないことも多いと考えられますが、書いておいて困ることもないので、入れておくとよいでしょう。公式ドキュメントでもそのようになっています。

compatibility_flagsは、個別の機能を有効にするフラグです。ここではnodejs_compatというNode.js互換のAPIを有効にするフラグを立てました。SSRのアダプターを使う場合は有効にする必要があります。

補足：compatibility_dateとcompatibility_flags

compatibility_dateは、workerdの挙動をどの時点のものに固定するかを指定するものです。ランタイムの仕様変更で既存のWorkerが壊れないようにするための仕組みで、新しくプロジェクトを作るときは、その日の日付を入れておけばよいです。日付を変更しなければ後方互換が担保され、新しい機能を使うようなタイミングではより新しい日付に書き換えるといった運用イメージです。

Compatibility dates | Cloudflare Docs

SSRなページを追加する

アダプターを入れただけでSSRに切り替わるわけではないので、SSRを指定したページを追加してみましょう。src/pages以下にはいまindex.astroしかありませんが、ssr.astroというファイルを追加します。Astroはデフォルトでは全ページを事前にレンダリング（SSG）します。オンデマンドにレンダリングしたいページでは、フロントマターに次の1行を書き加えます。

このページだけSSRにする

---
export const prerender = false;
---

補足：サイト全体をSSRにする場合

もし、サイトの大部分が動的なのであれば、astro.config.mjsでoutput: 'server'を指定して全ページをSSRにし、SSGでよいページにだけexport const prerender = trueを書く、という形にもできます。

ではこちらもデプロイしてみましょう。その前にnpm run buildを実行しておきます。mainに指定した@astrojs/cloudflare/entrypoints/serverは、ビルドを通して実際のWorkerのコードに解決される仕組みなので、ビルドしていないとエントリーポイントが見つからないというエラーになります。

先ほどと同様にnpx wrangler deployでサイトに反映することもできますが、ここではnpx wrangler versions uploadとしてみてください。こうするといきなり本番にデプロイされるのではなく、別のURLでプレビューができるようになります。

アップロードに成功すると、ターミナルにVersion Preview URL: https://...という行が出力されるはずです。Cloudflare Workersは、このようにバージョンごとに本番とは別のURLを発行し、プレビューができるようにしてくれます。ローカルプレビューと違って、インターネット上でアクセス可能なURLなので、誰かに共有したり、別の端末から確認したりすることも簡単にできます。

また、Cloudflareのダッシュボードで、「デプロイ」の画面を見てみましょう。一番上の「アクティブな展開」は更新されておらず、その次の「バージョン履歴」のところには新しいバージョンが追加された状態になっています。プレビューでSSRのページにアクセスできること、本番のサイトにはSSRのページがまだ存在しないことを確認してみてください。

これで、SSGもSSRもできるようになりました。また、本番デプロイの前に、プレビューで確認することもできるようになりました。

GitHubリポジトリと連携する

手元からのデプロイができるようになりましたが、このままでは何か更新するごとに手動でWranglerのコマンドを実行しなければなりません。Astroインストール時に、Gitの初期化もしていますので、実際の運用では、GitHubにpushしたら自動でデプロイされてほしいところです。この機能がWorkers Buildsです。

Builds | Cloudflare Docs

これまでの作業をコミットし、GitHubにアップロードしておきます。その前に、.wranglerというWranglerがローカル用のデータを保存するディレクトリが作られていると思いますので、これを.gitignoreに追加しておきます。GitHubリポジトリは、プライベートでもかまいません。

設定する項目

連携には、GitHubアカウント側に「Cloudflare Workers and Pages」というアプリ（GitHub Apps）がインストールされている必要があります。初めての場合はまずGitHubの画面でインストールを済ませておいてください。Workersとの接続設定はCloudflareのダッシュボードから行います。Workerの「設定」画面にある「ビルド」という項目のところに、「Git リポジトリ」とありますので、右端の「接続」をクリックします。

補足：連携しているのにプルダウンメニューに目当てのリポジトリがない

アプリをインストールしてCloudflareとGitHubのアカウント連携が済んでいるのに、Workers側のプルダウンメニューに目的のリポジトリがないという場合は、GitHubのアカウント設定のSettings > Integrations > Applicationsへ移動し、Cloudflareアプリの設定を更新する必要があります。「Installed GitHub Apps」タブに並んでいる「Cloudflare Workers and Pages」の右端の「Configure」ボタンから「Repository access」へ進み、該当のリポジトリを追加してください。

スクリーンショット：GitHubのApplications設定で「Cloudflare Workers and Pages」を開いた画面。上部の「Permissions」には、メタデータの読み取りと、administration、checks、code、deployments、pull requestsの読み書きが許可されていると表示されている。下部の「Repository access」では「Only select repositories」が選ばれ、赤枠で強調された「Select repositories」ボタンの下に「Select at least one repository.」という警告が出ている

リポジトリを選択できたら、ほかの項目はデフォルトで入っているもので大丈夫です。そして、ここまで進んできた方なら、入っている値がどういう意味かもわかると思います。

ビルドコマンドやデプロイコマンドは先ほどターミナルから実行したものと同じですね。もう1つ、「非本番ブランチのビルド」というチェック項目がありますが、これは本番ブランチ以外が更新された場合、プレビューをデプロイするかどうか、ということです。その下の「詳細設定」を開くと、「非本番ブランチのデプロイコマンド」として、こちらも先ほど実行したnpx wrangler versions uploadが入力されています。

つまり、Gitでブランチを切って作業し、それをGitHubにpushしたら、自動的に先ほどのようなプレビューページができあがるようになります。サイトを運用していく中ではとても便利な機能です。プルリクエストの画面には、自動的にプレビューURLを案内するコメントがつくようにもなります。

運用時のポイント

ここまでで、デプロイの仕組みはひととおり整いました。ここからは、実際にサイトを公開してから気になってくる点を2つ取り上げます。

プレビューへのアクセスを制限する

プレビューの内容は一般に公開したくない場合も多いでしょう。そのような場合には、ダッシュボードの「ドメイン」画面からアクセス制限を追加することもできます。

Cloudflareのアクセス制御については、別途記事にまとめていますので、必要に応じて参照してみてください。

Cloudflare Accessではじめるアクセス制御

デフォルトの404画面を独自のものに差し替える

SSGのみでアセットが見つからなかった場合、そのままだとCloudflareが用意する404画面が表示されます。独自の画面を表示したい場合は、404.htmlを用意します。そして、wrangler.jsoncにnot_found_handlingというキーを追加し、404-pageにしておくと、どのアセットにも一致しなかったリクエストには、ビルド済みの404.htmlが静的に返されます。

404ページを用意する（wrangler.jsonc）

"assets": {
  "directory": "./dist",
  "binding": "ASSETS",
  "not_found_handling": "404-page",
}

Worker script routing | Cloudflare Docs

ここまでのまとめ

今回は、Astroで作ったサイトをCloudflare Workersにデプロイしました。アダプターを追加し、手元からデプロイし、GitHubリポジトリと連携させて、本番ブランチへのpushで自動デプロイ、それ以外のブランチではプレビューURLが発行される、という状態まで到達できました。

次回はNext.jsでの事例を紹介します。また、ローカルでの開発やCloudflareのほかのサービスとの連携についても取り上げていく予定です。