Contents
スポンサードリンク
前提条件と環境準備
このセクションでは、Cloudflare Workers をローカルで動作させるために最低限必要なツールとアカウントの取得手順を解説します。Node.js と npm（または Yarn）が正しくインストールされていないと wrangler コマンドが実行できず、以降のすべての作業が失敗するため、最初に環境構築を完了させることが重要です。
必要なツール
- Node.js（v18 以上）
- npm（標準付属）または Yarn（任意）
- Cloudflare アカウント（無料で作成可能）
Node.js のインストール（公式・パッケージマネージャ推奨）
Node.js を tar 圧縮から展開して手動配置する方法は保守性が低く、バイナリの更新やパス設定にミスが起きやすいです。ここでは OS 別に公式インストーラまたは主流パッケージマネージャを利用したインストール例を示します。
| OS | 推奨インストール方法 | コマンド例 |
|---|---|---|
| macOS (Intel/Apple Silicon) | Homebrew で管理するとアップデートが容易 | brew install node@18 brew link --overwrite node@18 |
| Linux (Ubuntu/Debian系) | apt 経由で公式リポジトリを追加 | bash<br># NodeSource のセットアップスクリプトを取得<br>curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -<br>sudo apt-get install -y nodejs<br> |
| Windows | 公式 MSI インストーラ（インタラクティブ） をダウンロードして実行 | https://nodejs.org/dist/v18.x/node-v18.20.0-x64.msi |
バージョン確認
|
1 2 3 |
node -v # 例: v18.20.0 npm -v # 例: 10.2.3 |
ポイント
- nvm（Node Version Manager）を利用すれば複数バージョンの切り替えが簡単です。
- インストール後は必ず PATH が正しく通っていることを which node で確認してください。
Wrangler CLI のインストールと認証方法
Wrangler は Cloudflare Workers 用の公式 CLI です。最新バージョンは npm パッケージとして配布されており、グローバルにインストールした後 OAuth 認証 または API Token による非対話モードで認証できます。
インストール
|
1 2 3 |
npm i -g @cloudflare/wrangler # 最新版が自動取得されます wrangler --version # 例: 2.14.0 が表示されれば OK |
認証オプション
| 方法 | 実行コマンド・手順 | 主な利用シーン |
|---|---|---|
| OAuth（対話型） | wrangler loginブラウザが起動し、Cloudflare アカウントでログインすると自動的にトークンが保存されます。 |
ローカル開発・手動デプロイ |
| API Token（非対話型） | 1. Cloudflare ダッシュボード > My Profile > API Tokens → 「Create Token」→「Edit Cloudflare Workers」権限を付与 2. 発行したトークンを環境変数 CLOUDFLARE_API_TOKEN に設定 bash\nexport CLOUDFLARE_API_TOKEN=YOUR_TOKEN # シェルに永続化する場合は ~/.bashrc 等へ追記\nwrangler whoami # トークンが有効か確認\n |
CI/CD、GitHub Actions など自動デプロイ環境 |
注意:
wrangler login --api-tokenは現在非推奨です。代わりに上記の環境変数またはwrangler configコマンドでトークンを設定してください。
プロジェクト作成と wrangler.toml 設定
テンプレート生成から wrangler.toml の必須項目まで、プロジェクトの土台を正しく構築することがデプロイ成功の鍵です。特に compatibility_date は毎月更新しないと「エンジンバージョンが古い」エラーが発生します。
テンプレート生成
|
1 2 3 4 5 6 |
# JavaScript プロジェクト wrangler init my-worker --type=javascript # TypeScript プロジェクト（推奨） wrangler init my-ts-worker --type=typescript |
src/ 配下に index.js または index.ts が生成され、基本的な package.json も自動作成されます。
wrangler.toml の主要項目と自動更新スクリプト
|
1 2 3 4 5 6 7 8 9 10 |
name = "my-worker" compatibility_date = "2024-09-01" # 手動で設定した例。CI では自動置換します。 # 公開環境変数（デバッグ用に限定的に使用） [vars] ENV = "development" # シークレットは CLI で別途登録 # wrangler secret put API_KEY < ./secrets/api_key.txt |
毎月の compatibility_date 自動更新例（GitHub Actions 用）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# .github/workflows/update-compat-date.yml name: Update compatibility_date on: schedule: - cron: '0 0 1 * *' # 毎月 1 日 00:00 UTC に実行 jobs: bump-date: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set current date (YYYY-MM-DD) id: date run: echo "date=$(date +%Y-%m-%d)" >> $GITHUB_OUTPUT - name: Update wrangler.toml run: | sed -i -E "s/^compatibility_date = \".*\"/compatibility_date = \"${{ steps.date.outputs.date }}\"/" wrangler.toml - name: Commit & push change uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: "chore: bump compatibility_date to ${{ steps.date.outputs.date }}" |
ポイント
-sedコマンドで行単位の置換を行うだけなので、CI の実行環境に依存しません。
-git-auto-commit-actionにより自動的にリポジトリへプッシュされるので、次回デプロイ時には常に最新の日付が使用されます。
ハンドラ実装とローカルテスト
Workers のエントリポイントは fetch イベントです。ここでは最小構成のハンドラを TypeScript と JavaScript 両方で示し、wrangler dev によるローカルテスト手順も併せて解説します。
fetch ハンドラ（TypeScript）
|
1 2 3 4 5 6 7 8 9 10 11 |
// src/index.ts export default { async fetch(request: Request): Promise<Response> { const url = new URL(request.url); const name = url.searchParams.get("name") ?? "World"; return new Response(`Hello, ${name}!`, { headers: { "content-type": "text/plain" }, }); }, }; |
JavaScript バージョン
|
1 2 3 4 5 6 7 8 9 10 11 |
// src/index.js export default { async fetch(request) { const url = new URL(request.url); const name = url.searchParams.get("name") || "World"; return new Response(`Hello, ${name}!`, { headers: { "content-type": "text/plain" }, }); }, }; |
ローカル開発サーバー
|
1 2 3 4 |
wrangler dev # デフォルトで http://127.0.0.1:8787 が起動 curl "http://127.0.0.1:8787/?name=Cloudflare" # => Hello, Cloudflare! |
- デバッグは
console.logをコードに埋め込み、ターミナル上でリアルタイムに確認できます。 wrangler dev --localで純粋な Node.js 環境だけを使うことも可能です（Edge ランタイムの差異検証向け）。
デプロイ手順と npm スクリプト
ローカルテストが完了したら 本番環境へデプロイします。wrangler publish が直接デプロイを行い、npm スクリプトでラップすれば CI でも同一コマンドを利用できます。
package.json にスクリプトを追加
|
1 2 3 4 5 6 7 8 |
{ "scripts": { "dev": "wrangler dev", "build": "tsc && wrangler publish --dry-run", // ビルドと構文チェックのみ "deploy": "wrangler publish" } } |
手動デプロイ
|
1 2 3 4 |
npm run deploy # 実際に Workers が Cloudflare に公開される # デプロイ完了後に表示された URL を確認 curl https://my-worker.<account>.workers.dev/ |
デプロイ前のチェックポイント
npm run buildで TypeScript のコンパイルエラーが無いか確認。wrangler secret listで必要なシークレットがすべて登録済みか検証。
CI/CD 自動デプロイ（GitHub Actions）とトラブルシューティング
CI 環境では対話型認証が使えないため、API Token と 環境変数 を組み合わせた非対話モードでのデプロイが標準です。また、compatibility_date の自動更新も同じワークフローに統合できます。
完全版 GitHub Actions ワークフロー
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
name: Deploy Cloudflare Workers on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Node.js (v18) uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies & Wrangler run: | npm ci # package-lock.json がある前提 npm i -g @cloudflare/wrangler - name: Update compatibility_date (optional) if: github.event_name == 'schedule' # 定期実行ジョブだけ実行したい場合 run: | CURRENT_DATE=$(date +%Y-%m-%d) sed -i -E "s/^compatibility_date = \".*\"/compatibility_date = \"${CURRENT_DATE}\"/" wrangler.toml - name: Authenticate with Cloudflare (non‑interactive) env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} run: | # 環境変数だけで認証が完了することを確認 wrangler whoami - name: Deploy Workers run: npm run deploy |
シークレット管理のベストプラクティス
- API Token（
CLOUDFLARE_API_TOKEN）は Edit Cloudflare Workers 権限だけを付与し、最小権限の原則に従います。 - Workers のシークレットは
wrangler secret put <NAME>で事前に登録し、GitHub Actions 側では同名環境変数として参照します（例:API_KEY）。
よくあるエラーと対処法
| エラー | 主な原因 | 推奨対策 |
|---|---|---|
Authentication failed (wrangler whoami がエラー) |
トークンの権限不足、シークレット未設定、または名前ミス | Cloudflare ダッシュボードで Edit Cloudflare Workers 権限を持つトークンを再作成し、GitHub の CLOUDFLARE_API_TOKEN に正しく登録 |
| compatibility_date is required | wrangler.toml が空白やフォーマットエラーになっている |
YYYY-MM-DD 形式で必ず設定。CI では上記の sed スクリプトで自動更新を組み込む |
Secret not found (wrangler secret get) |
Workers 側にシークレットが未登録、または名前相違 | ローカルで wrangler secret put <NAME> を実行し、GitHub Actions の env でも同名変数を使用 |
| Build failed (tsc error) | TypeScript の型エラーや依存パッケージ未インストール | ローカルで npm run build（dry-run）を先に走らせ、コンパイルエラーをすべて解消 |
ポイント：CI のログはそのまま対処法のヒントになることが多いです。エラーメッセージをコピーして公式ドキュメントや GitHub Issues を検索すると迅速に原因が特定できます。
まとめ
- Node.js は公式インストーラまたは Homebrew / apt 等のパッケージマネージャで導入し、バージョン管理ツール (
nvmなど) の活用を推奨。 - Wrangler CLI は npm グローバルインストール後、OAuth（対話型）か API Token（非対話型）で認証。CI 環境では環境変数
CLOUDFLARE_API_TOKENを使用。 - プロジェクト作成は
wrangler init … --type=javascript|typescript、wrangler.tomlの必須項目は name・compatibility_date・vars/secret。毎月のcompatibility_dateは GitHub Actions のスクリプトで自動置換可能。 - ハンドラ実装は fetch イベントをエクスポートし、
wrangler devでローカルテスト。デバッグはconsole.logが有効。 - デプロイは
wrangler publish（または npm script）で実行。--dry-runを活用すればビルドエラーを事前に検出できる。 - CI/CD は GitHub Actions で API Token 認証＋自動
compatibility_date更新を組み合わせ、シークレットは Cloudflare と GitHub の二重暗号化で安全に管理。 - トラブルシューティングはエラーメッセージを手掛かりに、上表の対策を順に試すと速やかに復旧できる。
以上のフローを実行すれば、Cloudflare Workers の開発・テスト・本番デプロイが一貫した手順で完了し、継続的インテグレーション／デリバリーまで自動化できます。ぜひ実際に試して、サーバーレス開発の生産性向上を体感してください。
スポンサードリンク