Cloudflare Wrangler と​ Pages Functions —— デプロイツールと​ Functions バンドル

Wrangler とは​何か

Wrangler（ラングラー）は​ Cloudflare​（クラウドフレア）​公式の​ CLI​（Command Line Interface＝コマンドライン上で​操作する​ツール）である。​Cloudflare の​ Workers / Pages​（サーバーレス実行環境と​ホスティングサービス）を​開発・デプロイ・管理する​ための​ツールであり、​要するに​自分の​コードを​ Cloudflare に​公開​（デプロイ）する​ための​道具である。

サーバーレスとは、​自前の​サーバーを​用意せず、​コードの​実行だけを​クラウドに​任せる​方​式を​指す。​Cloudflare 上では​データセンターの​エッジ​（＝利用者に​地理的に​最も​近い​拠点）で​実行される​ため、​レイテンシ（＝応答までの​遅延）が​低い。

Wrangler の​主な​操作

# ローカルで開発サーバーを起動（本番に近い環境を手元で再現）
wrangler dev

# Cloudflare 本番環境にデプロイ（公開）
wrangler deploy

Cloudflare Pages Functions とは​何か

Cloudflare Pages は​静的サイト​（HTML/CSS/JS）を​ホスティングする​サービスである。Pages Functions は、​そうした​静的サイトに​追加できる​サーバーレス関数であり、​フロントエンドのみの​サイトに​ API などの​バックエンド処理を​追加できる。

実装は​シンプルで、​リポジトリにfunctions/ディレクトリを​作りファイルを​置くだけである。​ファイル名が​ URL パスに​なると​いう​規約が​あり、​例えばfunctions/api/hello.jsは/api/helloで​アクセスできる。

Functions バンドルとは​何か

ビルド時に、functions/ディレクトリ内の​すべての​ファイルが​1つの​ Worker に​まとめられる。​これをFunctions バンドル（＝複数の​関数を​1つに​まとめた​成果物）と​呼ぶ。バンドルとは​複数の​ファイルを​1つに​まとめる​ことを​指し、​Webpack のような​ JavaScript の​ビルドツールでも​同じ​概念が​使われる。

Pages Functions で​ REST API を​作る

Pages Functions ではREST API（＝HTTP の​定められた​作法に​従って​データを​やり取りする​ API）を​実装できる。​一般的な​パターンは、​エンドポイント​（＝入口と​して​呼び出す URL）をfunctions/api/配下に​置く​ことである。

// functions/api/items.js — GET /api/items に対応
export async function onRequestGet(context) {
return Response.json({ items: ["A", "B", "C"] });
}

「REST API が​動かない」​典型的な​原因

1. functions/ の​配置ミス：リポジトリルートのfunctions/に​ファイルが​なければ​ビルドに​含まれない。
2. ルーティング規約の​誤解：ファイル名＝URL パスと​いう​規約を​理解していないと、​意図しない​パスに​ファイルを​置いてしまう。​動的パラメーターは[id].jsのように​ブラケット記法で​書く。
3. ビルド設定の​不備：Cloudflare Pages の​ダッシュボードで​ Functions が​有効に​なっているか​確認する。
4. _routes.json の​除外設定：_routes.json（ルーティング制御ファイル）の​除外リストに/api/*が​入っていると、​Functions が​呼ばれず静的ファイル扱いに​なる。
5. Workers と​ Pages の​混同：Workers と​ Pages Functions は​どちらも​ Cloudflare 上で​コードを​実行する​方​法だが、​設定方​法やwrangler.toml（Wrangler の​設定ファイル）の​書き方が​異なる。

Wrangler と​ Pages Functions の​関係まとめ

役割	担当
コードを​書く​場所	functions/ディレクトリ
ローカルでの​実行	wrangler dev
本番への​公開	wrangler deploy、​または​ Cloudflare Pages の​ Git 連携に​よる​自動デプロイ
ビルド時の​成果物	Functions バンドル​（単一の​ Worker）

Cloudflare Pages を​使う​場合、​GitHub リポジトリと​連携すれば​ main ブランチへの​ push で​自動デプロイされる​ため、wrangler deployを​手動で​実行しない​構成に​する​ことが​一般的である。

出典・参考

元の​ノートに​外部の​出典リンクは​記載されていない。