2026年版 Wrangler v2 と GitHub Actionsで始める Cloudflare Workers デプロイ

2026年6月1日

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

Contents

1 1. Cloudflare Workers とランタイムの概要
2 2. Wrangler CLI のセットアップとプロジェクト初期化
3 3. ローカルテストとデバッグ手法
4 4. 本番環境へのデプロイとオプション
5 5. GitHub Actions で CI/CD パイプライン構築
- 5.1 5.1 基本的な Workflow YAML
  - 5.1.1 キーポイント
- 5.2 5.2 フレームワーク別注意点（例: SvelteKit）
6 6. Cloudflare Pages と Workers の統合（2024 年時点）
- 6.1 6.1 現状のサポートレベル
- 6.2 6.2 同一リポジトリで Pages と Workers を管理する構成例
7 7. まとめ

スポンサードリンク

1. Cloudflare Workers とランタイムの概要

Cloudflare のエッジネットワーク（300 カ所以上）で JavaScript/TypeScript や Rust → WebAssembly (Wasm) を実行できるサーバーレスプラットフォームが Workers です。

JavaScript/TypeScript はフロントエンド開発者にとって学習コストが低く、npm パッケージや Node.js 互換モジュールをそのまま利用できます。
Rust は Wasm にコンパイルされ、CPU バウンドな処理や安全性が求められるユースケースで高い性能を発揮します。

選択の指針
- 開発スピードとチームスキル：既に TypeScript が主流なら Workers の JS/TS ランタイムが最適。
- 実行性能・リソース制限：大規模な計算やメモリ使用量が多い処理は Rust → Wasm が有利。
- エコシステムの成熟度：KV、D1、Durable Objects など Cloudflare のサービスとの統合は TS 側が先行しています。

2. Wrangler CLI のセットアップとプロジェクト初期化

2.1 インストール手順（npm と Homebrew）

ローカル環境に Wrangler v2 を導入する最も簡単な方法は、npm または macOS/Linux 用の Homebrew です。どちらでも同等の機能が提供されます。

# npm（推奨）
npm install -g wrangler@latest

# Homebrew（macOS / Linuxbrew）
brew install cloudflare/cloudflare/wrangler

# npm（推奨）

npm install -g wrangler@latest

# Homebrew（macOS / Linuxbrew）

brew install cloudflare/cloudflare/wrangler

インストール後はバージョンを確認し、2.x 系以上であることを必ずチェックしてください。

wrangler version   # 例: Wrangler 2.12.0

1 2	wrangler version # 例: Wrangler 2.12.0

ポイント：wrangler -V は非推奨です。公式ドキュメントは wrangler version を使用するよう案内しています。

2.2 プロジェクト作成とテンプレート選択

wrangler init コマンドで新規プロジェクトを生成できます。--type フラグにより言語やフレームワークの雛形を指定します。

テンプレート	用途・特徴
`workers-ts`	TypeScript のシンプルな Workers
`workers-rust`	Rust → Wasm 用のビルド設定が自動生成
`pages-functions`	Cloudflare Pages と統合した Functions

# TypeScript プロジェクト例
wrangler init my-worker --type=javascript

# TypeScript プロジェクト例

wrangler init my-worker --type=javascript

2.3 `wrangler.toml` の主要設定項目

プロジェクト作成時に自動生成される wrangler.toml は、デプロイ先やバインディング情報を一元管理します。代表的な項目と推奨設定は以下の通りです。

name = &quot;my-worker&quot;
account_id = &quot;&lt;YOUR_ACCOUNT_ID&gt;&quot;
compatibility_date = &quot;2024-01-01&quot;   # ランタイム機能保証日

# ルーティング（任意）
routes = [{ pattern = &quot;example.com/api/*&quot;, zone_id = &quot;&lt;ZONE_ID&gt;&quot; }]

# KV バインディング例
kv_namespaces = [
  { binding = &quot;MY_KV&quot;, id = &quot;&lt;KV_NAMESPACE_ID&gt;&quot; }
]

# D1 データベースのバインディング例
d1_databases = [
  {
    binding = &quot;DB&quot;,
    database_name = &quot;mydb&quot;,
    preview_database_name = &quot;mydb_preview&quot;
  }
]

name = "my-worker"

account_id = "<YOUR_ACCOUNT_ID>"

compatibility_date = "2024-01-01" # ランタイム機能保証日

# ルーティング（任意）

routes = [{ pattern = "example.com/api/*", zone_id = "<ZONE_ID>" }]

# KV バインディング例

kv_namespaces = [

{ binding = "MY_KV", id = "<KV_NAMESPACE_ID>" }

]

# D1 データベースのバインディング例

d1_databases = [

{

binding = "DB",

database_name = "mydb",

preview_database_name = "mydb_preview"

}

]

account_id と name は Cloudflare ダッシュボードから取得し、必ず設定してください。
compatibility_date を明示することで、将来の破壊的変更からコードを保護できます。
routes が空の場合は Workers が全トラフィックに適用されますが、特定パスだけに限定したいときに使用します。
環境ごとの差分管理 は --env オプションで切り替えられる [env.*] セクションを利用すると CI/CD が楽になります。

3. ローカルテストとデバッグ手法

3.1 `wrangler dev` でエッジ環境をシミュレート

ローカル開発時は wrangler dev が提供するエミュレーションサーバーで、実際の Workers と同様の動作を確認できます。

wrangler dev   # デフォルト: http://localhost:8787

1 2	wrangler dev # デフォルト: http://localhost:8787

環境変数：.dev.vars に KEY=VALUE 形式で記述し、コード内では process.env.KEY で取得可能です。
KV モック：インメモリ KV が自動的に提供され、MY_KV.put() / get() が即座に反映します。

3.2 プレビュー URL の取得（`wrangler preview`）

GitHub Pull Request やブランチごとの確認が必要なときは、プレビューモード を利用します。現在の公式 CLI では --branch オプションはサポートされていません。その代わりに次のコマンドで一時的な公開 URL を取得します。

wrangler preview   # プレビュー用の一時 URL が出力されます

1 2	wrangler preview # プレビュー用の一時 URL が出力されます

この URL は Cloudflare のエッジネットワーク上に作成され、本番トラフィックとは分離された環境です。プルリクエストと連携させる場合は、GitHub Actions で wrangler preview を実行し、出力した URL をコメントとして投稿すると便利です。

3.3 デバッグポイント

手法	説明
コンソールログ	`console.log()` はローカル端末と Chrome DevTools の両方に表示されます。
Chrome DevTools	`http://localhost:8787/__inspect` にアクセスすると、ブレークポイントやステップ実行が可能です。
例外ハンドリング	`try/catch` 内で `return new Response(err.message, {status: 500})` とすれば、エラーメッセージがレスポンスに乗ります。

ベストプラクティス：ローカル開発は必ず wrangler dev → wrangler preview のフローで行い、環境変数・KV のモックを活用して本番に近い挙動を検証しましょう。

4. 本番環境へのデプロイとオプション

4.1 基本コマンド `wrangler publish`

ローカルで問題が確認できたら、publish コマンドでエッジ全体に即時反映させます。

wrangler publish   # デフォルトは production 環境へデプロイ

1 2	wrangler publish # デフォルトは production 環境へデプロイ

4.2 主なオプションの使い分け

オプション	用途
`--env <environment>`	`[env.*]` に定義した設定（例: staging, production）を切り替える。
`--dry-run`	ビルド結果と差分だけを表示し、実際のデプロイは行わない。CI パイプラインで安全確認に使用。
`--script <path>`	デフォルト以外のエントリーポイントを指定したい場合に利用（主にカスタムビルドフロー向け）。

注意：--branch は Pages のプレビュー機能でのみ利用可能です。Workers のデプロイ時には --env や --dry-run を組み合わせて環境管理してください。

4.3 よくあるエラーと対処法

エラー種別	主な原因	推奨対策
認証エラー (`CF_API_TOKEN` が無効)	トークン期限切れ、権限不足	Cloudflare ダッシュボードで Workers Scripts と KV Storage など必要最低限のスコープを付与し、GitHub Secrets を再設定。
クォータ超過 (`Quota Exceeded`)	KV/D1 の書き込み上限やリクエスト数に達した	ダッシュボードで使用量を確認し、プランアップグレードまたはアクセス頻度の削減を検討。
ビルド失敗（TypeScript / Rust）	コンパイルエラー、依存関係の不整合	`wrangler dev` でエラーログを確認し、`tsconfig.json` や `Cargo.toml` の設定を修正。

デプロイ前に必ず --dry-run を実行し、差分と認証情報が期待通りか確認する習慣をつけましょう。

5. GitHub Actions で CI/CD パイプライン構築

5.1 基本的な Workflow YAML

以下は Node.js + TypeScript プロジェクト向けの最小構成です。push と pull_request の両方で実行し、main ブランチへのマージ時に本番デプロイします。

name: Deploy Cloudflare Workers

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # OIDC 用（必要に応じて）

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Cache node_modules
        uses: actions/cache@v3
        with:
          path: |
            ~/.npm
            node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Install dependencies
        run: npm ci

      - name: Build (TypeScript)
        run: npm run build   # tsc が走る想定

      - name: Install Wrangler
        run: npm install -g wrangler@latest

      - name: Deploy to Cloudflare Workers
        env:
          CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
        run: |
          # ステージング環境でのプレビュー（任意）
          if [[ &quot;${{ github.event_name }}&quot; == &quot;pull_request&quot; ]]; then
            wrangler preview
          else
            wrangler publish --env production --dry-run   # まずは dry-run
            wrangler publish --env production
          fi

name: Deploy Cloudflare Workers

on:

push:

branches: [ main ]

pull_request:

branches: [ main ]

jobs:

build-and-deploy:

runs-on: ubuntu-latest

permissions:

contents: read

id-token: write # OIDC 用（必要に応じて）

steps:

- name: Checkout repository

uses: actions/checkout@v4

- name: Set up Node.js

uses: actions/setup-node@v3

with:

node-version: '20'

- name: Cache node_modules

uses: actions/cache@v3

with:

path: |

~/.npm

node_modules

key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

restore-keys: |

${{ runner.os }}-node-

- name: Install dependencies

run: npm ci

- name: Build (TypeScript)

run: npm run build # tsc が走る想定

- name: Install Wrangler

run: npm install -g wrangler@latest

- name: Deploy to Cloudflare Workers

env:

CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

run: |

# ステージング環境でのプレビュー（任意）

if [[ "${{ github.event_name }}" == "pull_request" ]]; then

wrangler preview

else

wrangler publish --env production --dry-run # まずは dry-run

wrangler publish --env production

キーポイント

Secrets の管理：CF_API_TOKEN は最小権限（Workers Scripts、KV Storage）だけ付与し、GitHub の Settings → Secrets に安全に保存します。
キャッシュ活用：actions/cache で node_modules をキャッシュするとジョブ実行時間が約30 %短縮できます。Rust プロジェクトの場合は ~/.cargo/registry と target ディレクトリも同様にキャッシュしてください。
プレビューと本番の分離：Pull Request のみでは wrangler preview を呼び出し、実際のデプロイは push（main ブランチ）時に限定しています。

5.2 フレームワーク別注意点（例: SvelteKit）

SvelteKit を Workers にデプロイする場合、公式アダプタ @sveltejs/adapter-cloudflare が提供するビルド設定と Wrangler のバンドラが衝突しやすいです。

Adapter の選択：SSR が必要なら adapter-cloudflare のみを使用。静的サイトは別ステージで adapter-static を走らせ、生成物だけを Pages にデプロイします。
環境変数の分離：.env.staging と .env.production を用意し、GitHub Actions では --env staging / --env production を切り替えてビルドします。

6. Cloudflare Pages と Workers の統合（2024 年時点）

6.1 現状のサポートレベル

Pages Functions および Workers for Sites は 2023 年末にベータリリースされた機能で、2024 年 Q2 にかけてパブリックプレビューが提供されています。したがって「公式にフルサポート」ではなく ベータ機能として利用可能 です。プロダクション環境で使用する際は以下を意識してください。

ベータ版のため、API の変更や不具合が発生する可能性があります。
Cloudflare ダッシュボードの「Pages → Settings → Functions」から有効化できます。

6.2 同一リポジトリで Pages と Workers を管理する構成例

プロジェクト構造（例）

/my-app
├─ public/          # Pages が出力する静的ファイル
├─ src/
│   ├─ workers/     # Workers 用コード (TS)
│   └─ pages/       # 静的サイトのソース（React/Vite 等）
└─ wrangler.toml

/my-app

├─ public/ # Pages が出力する静的ファイル

├─ src/

│ ├─ workers/ # Workers 用コード (TS)

│ └─ pages/ # 静的サイトのソース（React/Vite 等）

└─ wrangler.toml

wrangler.toml の設定

name = &quot;my-app&quot;
account_id = &quot;&lt;YOUR_ACCOUNT_ID&gt;&quot;
compatibility_date = &quot;2024-01-01&quot;

# Pages 側のビルドディレクトリを Workers にバインド
[site]
bucket = &quot;./public&quot;          # Pages が生成した静的ファイル
entry-point = &quot;src/workers&quot;  # Workers のエントリーポイント

# KV や D1 の例（必要に応じて）
kv_namespaces = [{ binding = &quot;MY_KV&quot;, id = &quot;&lt;KV_ID&gt;&quot; }]

name = "my-app"

account_id = "<YOUR_ACCOUNT_ID>"

compatibility_date = "2024-01-01"

# Pages 側のビルドディレクトリを Workers にバインド

[site]

bucket = "./public" # Pages が生成した静的ファイル

entry-point = "src/workers" # Workers のエントリーポイント

# KV や D1 の例（必要に応じて）

kv_namespaces = [{ binding = "MY_KV", id = "<KV_ID>" }]

GitHub Actions での一括デプロイ

- name: Build Pages (static)
  run: |
    npm ci
    npm run build   # ビルド結果が ./public に出力される想定

- name: Deploy Pages + Workers
  env:
    CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
    CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
  run: |
    # まずは Pages のビルド成果物をアップロード（wrangler pages publish）
    wrangler pages publish ./public --project-name my-app
    # 次に同一リポジトリ内の Workers をデプロイ
    wrangler publish --env production

- name: Build Pages (static)

run: |

npm ci

npm run build # ビルド結果が ./public に出力される想定

- name: Deploy Pages + Workers

env:

CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

run: |

# まずは Pages のビルド成果物をアップロード（wrangler pages publish）

wrangler pages publish ./public --project-name my-app

# 次に同一リポジトリ内の Workers をデプロイ

wrangler publish --env production

ポイント：ベータ機能であることを踏まえ、ステージング環境で十分にテストした上で本番へプッシュしてください。

7. まとめ

項目	キーとなる知見
ランタイム選択	TS は開発速度とエコシステム、Rust/Wasm は計算性能に強み。用途に応じて使い分けを推奨。
Wrangler の導入	`npm install -g wrangler@latest` → `wrangler version` で確認。`wrangler.toml` に環境別設定 (`[env.*]`) を記述し、CI から `--env` で切替える。
ローカルテスト	`wrangler dev` でエミュレーション、`.dev.vars` で環境変数、`wrangler preview` で一時公開 URL を取得。デバッグは Chrome DevTools の `__inspect` エンドポイントが便利。
本番デプロイ	`wrangler publish --env <stage>` が基本。`--dry-run` で差分確認し、認証エラーやクォータ超過に備える。
CI/CD	GitHub Actions に `npm ci` → `npm run build` → `wrangler publish` を組み込み、Secrets とキャッシュを活用して高速かつ安全なパイプラインを構築。
Pages + Workers の統合	ベータ機能（Pages Functions / Workers for Sites）を利用し、同一リポジトリで `wrangler.toml` の `[site]` ブロックにビルドディレクトリを指定すれば、一括デプロイが可能。

本ガイドの手順とベストプラクティスを踏むことで、開発から本番運用まで一貫したフロー を構築できます。最新情報は常に Cloudflare の公式ドキュメント（https://developers.cloudflare.com）をご確認ください。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

-Cloudflare

comment コメントをキャンセル

: Cloudflare

Zero TrustとCloudflare Oneの基本と導入事例 – 2026年最新ガイド

Zero Trustの原則とCloudflare Oneが提供するZTNA、SWG、CASB、IDaaSを活用した導入事例と効果、実装手順を徹底解説します。

: Cloudflare

Cloudflare Workersで認証付きサーバーレスAPIを構築・自動デプロイ

本ハンズオンでは Cloudflare Workers と Wrangler による認証付きサーバーレス API の設計・実装から、GitHub Actions を用いた自動デプロイまでを具体的に解説します。

: Cloudflare

Cloudflare Zero Trust（Cloudflare One）とは？2026年最新構成と無料プラン設定

Zero TrustモデルとCloudflare Zero Trustの最新コンポーネント、無料プランでの導入手順をわかりやすく紹介します。

: Cloudflare

2026年Cloudflare WAF無料設定ガイド

本記事では、2026年のCloudflare WAF無料プラン設定手順を具体的に解説。無料登録・ドメイン接続・ルールセット選択・攻撃検証の全ステップと制限対策を紹介します。

: Cloudflare

Cloudflare Workers料金比較2026｜導入検討のポイント

Cloudflare Workersの2026年料金体系と導入検討ポイントを解説。無料枠・Paidプラン比較やコスト最適化戦略、競合サービスとの比較情報を提供しています。

2026年Cloudflare WAF無料設定ガイド

Steam Deckバッテリー長持ちの裏技：TDP調整と最適な設定方法

2026年版 Wrangler v2 と GitHub Actionsで始める Cloudflare Workers デプロイ

1. Cloudflare Workers とランタイムの概要

2. Wrangler CLI のセットアップとプロジェクト初期化

2.1 インストール手順（npm と Homebrew）

2.2 プロジェクト作成とテンプレート選択

2.3 wrangler.toml の主要設定項目

3. ローカルテストとデバッグ手法

3.1 wrangler dev でエッジ環境をシミュレート

3.2 プレビュー URL の取得（wrangler preview）

3.3 デバッグポイント

4. 本番環境へのデプロイとオプション

4.1 基本コマンド wrangler publish

4.2 主なオプションの使い分け

4.3 よくあるエラーと対処法

5. GitHub Actions で CI/CD パイプライン構築

5.1 基本的な Workflow YAML

キーポイント

5.2 フレームワーク別注意点（例: SvelteKit）

6. Cloudflare Pages と Workers の統合（2024 年時点）

6.1 現状のサポートレベル

6.2 同一リポジトリで Pages と Workers を管理する構成例

7. まとめ

2.3 `wrangler.toml` の主要設定項目

3.1 `wrangler dev` でエッジ環境をシミュレート

3.2 プレビュー URL の取得（`wrangler preview`）

4.1 基本コマンド `wrangler publish`