💨

Cloudflare Pages× Workers、GitHub Actionsとは？　初学者インターン生がわかりやすくまとめてみた。

kankan

2025/08/20に公開

 Cloudflare Pages×WorkersのCI/CD運用
 はじめに普段Webアプリを開発していて、Cloudflare WorkersやPagesの設定をいじったり、手動でビルド・デプロイをした経験はありませんか？私自身、あるプロジェクトでCloudflare WorkersとPagesを組み合わせて開発を行う中で、ビルドやデプロイの順番によって動作確認がうまくできないといった問題に何度も直面しました。しかし、CI/CDの導入と構成の整理によって、Pushするだけで期待通りに動く状態を実現できるようになり、開発効率も大幅に改善されました。

　この記事では、そうしたCloudflare Pages × Workersを活用したCI/CD構成について、初心者にもわかりやすくまとめていきます。特に、私が実際に遭遇した課題や、導入してよかった工夫についても交えて解説します！

 現状の動作パターン現在の構成では、frontend・backendの修正状況によって、ビルドされるコンポーネント(workers/pages)や接続先が変化します。それによって、思ったように動作確認ができないケースがしばしば発生しています。以下に代表的な3パターンを整理しました。

 frontend のみ修正された場合
frontend/workers と frontend/pages がビルドされる。
しかし、frontend/workers は backend に接続されていないため、

SSRやAPI fetchの動作確認ができない。
一方、frontend/pages は「最後にデプロイされた dev/backend」を参照するため、

見た目の変更だけであれば確認可能。

 backend のみ修正された場合
backend/workers のみがビルドされる。

pages はビルドされない（UIは更新されない）。

workers@reference を使えば API 動作の確認は可能。
ただし、UIとの整合性やSSRとの接続確認はできない。

 frontend ＋ backend 両方修正された場合
frontend/workers, backend/workers, pages のすべてがビルドされる。

最新状態の frontend + backend の接続が再現されるため、理論上は完全な動作確認が可能。
ただし、ビルドタイミングのズレによって frontend が古い backend を参照する可能性もある。

 なぜ困るのか？「CIが通ったのに、実際の動作確認はできない」
「表示は更新されたけどAPIが古い」
「修正内容と表示結果が一致しない」

といった開発効率や信頼性を損なう状態が生じています。
次章では、少し専門的な単語が出てきてしまったので、それの解説を行います。

 用語・構成整理この章では、専門用語とCloudflare Pages× Workersにおける主要な用語や構成の違いを整理していきます。

 ビルド / デプロイ / dev の違い

用語
意味
目的
例


ビルド（build）
ソースコードを本番実行形式に変換する処理
最適化・圧縮・準備
npm run build

デプロイ（deploy）
ビルド成果物をWebサーバーに配置する処理(リモートのものを動かすイメージ)
インターネットからアクセス可能にする

vercel deploy, GitHub Actions

開発モード（dev）
ビルドせず即座に反映される開発専用サーバー(ローカルのものを動かすイメージ)
実装中のリアルタイム確認
npm run dev


 Workers と Pages の違い

項目
Cloudflare Workers

Cloudflare Pages



役割
APIやSSRなど裏方処理
UIの表示（静的ページ）

実行場所
エッジ環境（グローバル分散）
ブラウザ or CDN

書く場所

+server.ts, APIルートなど

+page.svelte, +layout.svelte


ユーザーに見える？
見えない
見える

💡 Workers＝裏方ロジック、Pages＝見た目の配信。

 各ディレクトリの役割（frontend/pages など）

ディレクトリ
内容
担当処理の例


frontend/pages
UI表示の静的ページ
HTML/CSS/JSの出力、ページ遷移

frontend/workers
SSRやMiddleware処理
リダイレクト、先読み、認証など

backend/workers
APIロジック処理
DBアクセス、JSONレスポンスなど


 SSR と CSR の違い

用語
意味
実行タイミング
例



SSR（サーバーサイドレンダリング）
サーバーでHTMLを生成
初回アクセス時
ブログ記事の初期描画など


CSR（クライアントサイドレンダリング）
ブラウザでJSがHTMLを生成
ユーザー操作後
モーダル、タブ切替など

Cloudflare PagesではSSRがfrontend/workers側、CSRがfrontend/pages（またはJS側）で担われます。

 動作確認が難しい理由この構成では以下のような要因で「期待どおりに確認できない」ことがあります：
frontendとbackendが別々にビルド・デプロイされる
Pagesは「最後にデプロイされたbackend」しか参照しない
SSR（＝frontend/workers）の中で呼び出すAPIが意図したbackendに繋がっていない可能性
修正内容とPreview結果がズレる
これらの用語を押さえた上で、次章では「CI/CDとは何か？なぜそれが大事なのか？」を解説していきます。

 Cloudflare WorkersとPagesの役割とは？
 Cloudflare Workersの役割Cloudflare Workersは、サーバサイドの処理を担う超軽量な実行環境です。

例えば
クライアント(ブラウザ)からのリクエストを受け取る
APIエンドポイントとして機能する
Cloudflare D1(SQLite)と接続してデータを読み書きする
必要に応じてSSR(サーバーサイドレンダリング)も担う


ディレクトリ
役割


frontend/workers
フロントエンドのSSR、APIとの仲介、ルーティングなどを担当

backend/workers
D1と接続してAPIロジックを処理（例：送信スケジュールのCRUD操作）

frontend/pages
ユーザーに表示される静的UI、CSRで動的UIも制御


 Cloudflare Pagesの役割Cloudflare Pagesは、静的サイトやフロントエンドアプリをデプロイ・ホスティングするためのサービスです。

例えば
ビルド済みのフロントエンド(HTML,CSS,JSD)を配信する。
ブラウザにダウンロードされてクライアントサイドで動く処理(CSR)を提供する
SSR(サーバサイドレンダリング)されないルートや、最初の読み込み時に使用される。


コンポーネント
内容


frontend/pages
Vite/SvelteKit によりビルドされた静的ファイル（主に CSR 用途）

Cloudflare Pages
これらの静的ファイルをクラウド上にホスティングし、ユーザーに高速配信


 GitHub Actionsとは？GitHub Actionsは、GitHub上でCI/CDを実現するための自動化ツールです。

リポジトリに設定ファイル*.yml）を書くことで、
コードのPushをトリガーに
テストやビルド
Cloudflareへのデプロイ

などの処理を自動で実行できます。


特徴
内容


自動化
手作業だったビルドやデプロイを自動化できる

柔軟性
任意のコマンド・処理を記述できる

Cloudflare連携

wrangler CLIでWorkersやPagesに連携可能


 CI/CDとは？ -自動化で開発の信頼性とスピードを上げる仕組みCI/CDは、現代のWeb開発における?自動化の中核を担う仕組みです。ソースコードをPushするあだけで、テストやビルド、デプロイといった工程が全て自動で進むようになります。

 CI（Continuous Integration：継続的インテグレーション）CIは、「開発者が行った変更を、頻繁に統合・検証するプロセス」を指します。
コードをGitHubにPushすると…
自動でテストが走る
コードのビルドが行われる

これにより、早期にバグを発見でき、開発スピードと品質が両立できます。

 CD（Continuous Delivery / Continuous Deployment）CIのあとに続くのがCDです。これは「変更内容を動作環境に届けるプロセス」です。


用語
内容
特徴


Continuous Delivery（継続的デリバリー）
本番環境には手動で承認してデプロイする
人間の確認ステップを挟める

Continuous Deployment（継続的デプロイ）
テストが通れば即座に本番に反映される
全自動で本番へ


 CloudflareにおけるCI/CDの例Cloudflare Pages と Workers を使うと、GitHubと連携することで以下のような自動化が可能です：
GitHubでmainやdevブランチにPush
Cloudflare側で自動的にビルド＆デプロイ

*.pages.dev のPreview URLで即時確認

 .github/workflows のファイルとは？修正方法を説明する前に、.github/workflows のファイルとは何かを整理しておきます。
GitHub Actions は、リポジトリの中に .github/workflows/ というフォルダを作り、その中に YAML ファイル（例：frontend.yml や backend.yml）を置くことで動作します。
つまり、
どんなタイミングで
どんな処理をするか
を定義するのが .github/workflows フォルダ内のファイルです。

 .github/workflows のファイルは何を定義する場所なの？例えば、YAML ファイルの中には次のようなことを定義します：
この workflow をいつ動かすか

（例：push 時、pull_request 時など）
どの OS 上で動かすか

（例：ubuntu-latest など）
どんなコマンドを実行するか

（例：ビルド、テスト、デプロイなど）
環境変数の設定
要するに、「GitHub 上で、手作業だった作業を自動化するための設計図」 がここに集まっているイメージです。

 どんなファイルがあるのか？私の担当するプロジェクトでは、以下のように分けています：


ファイル名
役割


backend.yml
backend のビルド & デプロイ

frontend.yml
frontend のビルド & デプロイ

cleanup-preview.yml
preview 環境の削除


 Preview 環境と dev 環境の違いPreview 環境では PR 単位で preview frontend と preview backend が作成されますが、それとは別に、開発ブランチ（例：dev）にも frontend/backend のビルド・デプロイが設定されています。
私のプロジェクトでは、Preview 環境と dev 環境の frontend/backend の参照先を、開発者が書いたコードの差分によって動的に切り替えられるようにすることを目指しました。

 各構成の役割とデプロイ先

種類
主な役割
デプロイ先


dev frontend
PR をマージした後の UI 確認
https://frontend.workers.dev

dev backend
API 処理の最新確認
https://backend.workers.dev

preview frontend
ユーザーが見る UI 表示確認
Cloudflare Pages / Workers

preview backend
API・認証など裏側のロジック確認
Cloudflare Workers


 環境ごとの用途と URL 例

環境
用途
URL 例


preview
PR ごとの動作確認用

https://frontend-pr-123.pages.dev など

dev
開発ブランチの最新状態を常に反映

https://backend.workers.dev など


 backend.yml の構成と役割backend.yml は、Cloudflare Workers 上にデプロイされるバックエンド（API 処理など）を自動的にビルド・デプロイする GitHub Actions の workflow です。

 主な役割
backend/ ディレクトリ内のコード変更を検知
必要な依存パッケージをインストール（例：pnpm install）

wrangler コマンドを使って Cloudflare Workers にデプロイ
PR 番号に応じた Preview 用 URL を自動生成
トリガー例
  pull_request:
    paths:
      - 'backend/**'
  push:
    branches:
      - main

 frontend.ymlの構成と役割frontend.ymlは、SvelteKitを使ったフロントエンドアプリケーションをビルド・デプロイするworkflowです。
主な役割として

・frontend/ ディレクトリ内のコードを検知

・APIの接続先(PUBLIC_BACKEND_URL)をPRに応じて動的に切り替え

・Cloudflare Pagesにビルド済みファイルをデプロイ

・PRコメントにpreview URLを自動投稿
トリガー例
  pull_request:
    paths:
      - 'frontend/**'
  push:
    branches:
      - dev

 修正方法
 私が行った主な変更点と工夫このプロジェクトでは、backend 側のコードや workflow には手を加えず、主に frontend のビルドプロセスと preview/backend の切り替えロジックに工夫を加えました。また、workflow 以外の周辺ファイルにも調整を行っています。


項目
内容
修正ファイル


差分検出の導入

git diff により backend に変更があったかを判定し、PUBLIC_BACKEND_URL を切り替え
.github/workflows/frontend.yml

preview backend の有無確認
curl によるヘルスチェックを通じて preview backend の URL を選定
.github/workflows/frontend.yml

fallback の実装
preview backend が存在しない場合、自動で dev backend に切り替える処理を追加
.github/workflows/frontend.yml

ビルドログの明示化
ビルド時に PUBLIC_BACKEND_URL を標準出力に表示し、環境の見える化を実現
.github/workflows/frontend.yml

PR コメント投稿機能

github-script を使って preview URL を直接 PR にコメント投稿（外部スクリプト未使用）
.github/workflows/frontend.yml

preview URL の自動生成・埋め込み
PR 番号から preview 環境の URL を構成し、環境変数やコメントに反映
.github/workflows/frontend.yml

変更差分に応じた接続先の切り替え

frontend/** のみ修正時でも backend の接続検証ができるように調整
.github/workflows/frontend.yml

共通スクリプト整理

scripts/deploy-preview.sh に実行権限を付与し、PUBLIC_BACKEND_URL を渡せるように修正
frontend/scripts/deploy-preview.sh

wrangler の引数修正

--arg backend_url=$PUBLIC_BACKEND_URL を渡して正しい backend にデプロイ
frontend/scripts/deploy-preview.sh

layout.svelte への環境変数出力

PUBLIC_BACKEND_URL を UI 側に反映し、どの backend に接続しているか確認可能に
frontend/src/routes/+layout.svelte


 動作確認【できるようになったことと動作確認】

・frontendだけ差分が出た場合、backendはdevのbackendを参照する。

↓GitHub actionsで表示されるURL



↓Cloudflare workersでの参照先

・backendだけ差分が出た場合、backendはpreview backendを参照する。

→GitHub Actions は dev ブランチとの変更差分を確認する仕組みであるが、今回の作業では frontend のファイルも変更に含まれているため、backend の差分だけを単独で確認することはできない。
・frontendとbackendが参照された場合、preview backendを参照する。

↓GitHub Actionsで表示されるURL



↓Cloudflareでの参照先

このように、GitHub Actions の構成を保ちながら preview 環境の接続先や確認体験を最適化する工夫を施しました。結果として、Push するだけで「最新のフロントエンド × 適切なバックエンド」に自動接続された preview 環境が生成される運用が実現できました。

用語	意味	目的	例
ビルド（build）	ソースコードを本番実行形式に変換する処理	最適化・圧縮・準備	`npm run build`
デプロイ（deploy）	ビルド成果物をWebサーバーに配置する処理(リモートのものを動かすイメージ)	インターネットからアクセス可能にする	`vercel deploy`, GitHub Actions
開発モード（dev）	ビルドせず即座に反映される開発専用サーバー(ローカルのものを動かすイメージ)	実装中のリアルタイム確認	`npm run dev`

項目	Cloudflare Workers	Cloudflare Pages
役割	APIやSSRなど裏方処理	UIの表示（静的ページ）
実行場所	エッジ環境（グローバル分散）	ブラウザ or CDN
書く場所	`+server.ts`, APIルートなど	`+page.svelte`, `+layout.svelte`
ユーザーに見える？	見えない	見える

ディレクトリ	内容	担当処理の例
`frontend/pages`	UI表示の静的ページ	HTML/CSS/JSの出力、ページ遷移
`frontend/workers`	SSRやMiddleware処理	リダイレクト、先読み、認証など
`backend/workers`	APIロジック処理	DBアクセス、JSONレスポンスなど

用語	意味	実行タイミング	例
SSR（サーバーサイドレンダリング）	サーバーでHTMLを生成	初回アクセス時	ブログ記事の初期描画など
CSR（クライアントサイドレンダリング）	ブラウザでJSがHTMLを生成	ユーザー操作後	モーダル、タブ切替など

ディレクトリ	役割
`frontend/workers`	フロントエンドのSSR、APIとの仲介、ルーティングなどを担当
`backend/workers`	D1と接続してAPIロジックを処理（例：送信スケジュールのCRUD操作）
`frontend/pages`	ユーザーに表示される静的UI、CSRで動的UIも制御

コンポーネント	内容
`frontend/pages`	Vite/SvelteKit によりビルドされた静的ファイル（主に CSR 用途）
Cloudflare Pages	これらの静的ファイルをクラウド上にホスティングし、ユーザーに高速配信

特徴	内容
自動化	手作業だったビルドやデプロイを自動化できる
柔軟性	任意のコマンド・処理を記述できる
Cloudflare連携	`wrangler` CLIでWorkersやPagesに連携可能

用語	内容	特徴
Continuous Delivery（継続的デリバリー）	本番環境には手動で承認してデプロイする	人間の確認ステップを挟める
Continuous Deployment（継続的デプロイ）	テストが通れば即座に本番に反映される	全自動で本番へ

ファイル名	役割
`backend.yml`	backend のビルド & デプロイ
`frontend.yml`	frontend のビルド & デプロイ
`cleanup-preview.yml`	preview 環境の削除

種類	主な役割	デプロイ先
dev frontend	PR をマージした後の UI 確認	https://frontend.workers.dev
dev backend	API 処理の最新確認	https://backend.workers.dev
preview frontend	ユーザーが見る UI 表示確認	Cloudflare Pages / Workers
preview backend	API・認証など裏側のロジック確認	Cloudflare Workers

環境	用途	URL 例
preview	PR ごとの動作確認用	https://frontend-pr-123.pages.dev など
dev	開発ブランチの最新状態を常に反映	https://backend.workers.dev など

項目	内容	修正ファイル
差分検出の導入	`git diff` により backend に変更があったかを判定し、`PUBLIC_BACKEND_URL` を切り替え	`.github/workflows/frontend.yml`
preview backend の有無確認	curl によるヘルスチェックを通じて preview backend の URL を選定	`.github/workflows/frontend.yml`
fallback の実装	preview backend が存在しない場合、自動で dev backend に切り替える処理を追加	`.github/workflows/frontend.yml`
ビルドログの明示化	ビルド時に `PUBLIC_BACKEND_URL` を標準出力に表示し、環境の見える化を実現	`.github/workflows/frontend.yml`
PR コメント投稿機能	`github-script` を使って preview URL を直接 PR にコメント投稿（外部スクリプト未使用）	`.github/workflows/frontend.yml`
preview URL の自動生成・埋め込み	PR 番号から preview 環境の URL を構成し、環境変数やコメントに反映	`.github/workflows/frontend.yml`
変更差分に応じた接続先の切り替え	`frontend/**` のみ修正時でも backend の接続検証ができるように調整	`.github/workflows/frontend.yml`
共通スクリプト整理	`scripts/deploy-preview.sh` に実行権限を付与し、`PUBLIC_BACKEND_URL` を渡せるように修正	`frontend/scripts/deploy-preview.sh`
wrangler の引数修正	`--arg backend_url=$PUBLIC_BACKEND_URL` を渡して正しい backend にデプロイ	`frontend/scripts/deploy-preview.sh`
layout.svelte への環境変数出力	`PUBLIC_BACKEND_URL` を UI 側に反映し、どの backend に接続しているか確認可能に	`frontend/src/routes/+layout.svelte`

Emoba Tech BlogPublication

エモバ株式会社のテックブログです。私たちはブロックチェーンやweb3、生成AI、ChatGPTやその他のLLM（Large Language Model）、AR/MR/VR等の様々な最先端のIT技術を駆使し、機能的な価値だけでなく情緒的な価値をお客様に提供します。

Cloudflare Pages× Workers、GitHub Actionsとは？　初学者インターン生がわかりやすくまとめてみた。

Cloudflare Pages×WorkersのCI/CD運用

はじめに

現状の動作パターン

frontend のみ修正された場合

backend のみ修正された場合

frontend ＋ backend 両方修正された場合

なぜ困るのか？

用語・構成整理

ビルド / デプロイ / dev の違い

Workers と Pages の違い

各ディレクトリの役割（frontend/pages など）

SSR と CSR の違い

動作確認が難しい理由

Cloudflare WorkersとPagesの役割とは？

Cloudflare Workersの役割

Cloudflare Pagesの役割

GitHub Actionsとは？

CI/CDとは？ -自動化で開発の信頼性とスピードを上げる仕組み

CI（Continuous Integration：継続的インテグレーション）

CD（Continuous Delivery / Continuous Deployment）

CloudflareにおけるCI/CDの例

.github/workflows のファイルとは？

.github/workflows のファイルは何を定義する場所なの？

どんなファイルがあるのか？

Preview 環境と dev 環境の違い

各構成の役割とデプロイ先

環境ごとの用途と URL 例

`backend.yml` の構成と役割

主な役割

frontend.ymlの構成と役割

修正方法

私が行った主な変更点と工夫

動作確認

Discussion