CloudflareのWorkers入門｜失敗しない始め方

2026年8月24日
Cloudflare

こんにちは。Osukeラーニング、運営者の「osuke」です。

Cloudflare Workersを使ってみたいものの、「何を準備すればよいのか」「ローカルでは動いたのに、公開時に設定で詰まらないか」と不安ではありませんか。Workersは小さなAPIやWebアプリを素早く公開できますが、最初から独自ドメイン、データベース、秘密情報まで一度に設定すると、失敗した場所を切り分けにくくなります。

結論からいうと、初心者はCloudflare公式のC3で最小プロジェクトを作り、wrangler devでローカル確認し、wrangler deployでworkers.devへ公開する順番がわかりやすいです。その後、用途に応じてCustom DomainかRouteを選びます。公開前にはcompatibility date、Secrets、Bindings、DNS、ログ、無料枠の6点を確認してください。

この記事はosuke本人のCloudflare Workers体験としては書かず、2026年8月24日時点のCloudflare公式資料と、Xで公開された開発者8人の初回デプロイ、設定の迷い、実装例を照合してまとめました。Xの内容は各投稿者の環境における一次情報であり、同じ時間や結果を保証するものではありません。Cloudflareの基本から確認したい方はCloudflareとは何かを初心者向けに解説した記事、アカウント作成がまだの方はCloudflareの始め方と初期設定を先にご覧ください。

記事のポイント

C3とWranglerで最小のWorkerを作成する
localhostで動作を確認してworkers.devへ公開する
Custom DomainとRouteを使い分ける
通常変数、Secrets、Bindingsを混同しない
ログとrollbackを用意して公開後の失敗に備える

Cloudflare Workersの始め方と準備

Cloudflare Workersの始め方は、最初に「何を公開するか」と「どの作成方法を使うか」を決めると迷いません。この章では、用途を最小化し、Node.jsとWranglerを準備し、Hello Worldをローカルで表示するところまで進めます。まだ独自ドメインやデータベースは設定せず、コードと実行環境だけを確認します。

Workersで何を公開できるか理解する

Cloudflare Workersは、Cloudflareのネットワーク上でJavaScriptやTypeScriptなどのコードを実行するサービスです。サーバーを1台用意して常時管理する形ではなく、HTTPリクエストを受けたときにエッジで処理します。最初の題材には、文字列を返すAPI、問い合わせの中継、URLリダイレクト、ヘッダー追加、軽量なWebページが向いています。

静的なHTMLを置くだけのサービスだと思う必要はありません。Xでは、Vatsal氏がブログアプリのバックエンドをWorkersとHono.jsで構築しながら学んでいる事例を公開しています。KV、D1、R2、Durable ObjectsなどをBindingで接続すれば、API、データ保存、ファイル配信、状態を持つ処理へ広げられます。ただし初回は外部資源を付けず、1つのレスポンスを返すWorkerから始めます。

用途を1文で決めてください。たとえば「/api/helloへアクセスするとJSONを返す」「古いURLを新しいURLへ301転送する」です。目的が曖昧なままテンプレートを選ぶと、Pages、Workers、Assets、Framework、D1などの選択肢が増え、どの機能が必要だったのかを見失います。最初の成功条件は、ブラウザで公開URLを開き、想定した文字列またはJSONが返ることだけで十分です。

初回に向く題材

Hello Worldを返す
現在時刻をJSONで返す
特定URLを301リダイレクトする
レスポンスヘッダーを1つ追加する
外部APIを1回呼び出して結果を整形する

Playground・Dashboard・CLIを選ぶ

Workersには、ブラウザだけで試せるPlayground、管理画面から作成するDashboard、手元のプロジェクトをWranglerで操作するCLIという主な入口があります。Cloudflare公式のDashboard手順では、Playgroundは設定なしの試用、DashboardはテンプレートやGitリポジトリからの開始に使えます。コードを継続して更新し、設定を履歴へ残すならCLIが基本です。

方法	向く用途	長所	注意点
Playground	数分の試用	アカウントやローカル準備なしで挙動を確認	継続運用の設定管理には向かない
Dashboard	画面操作・Git連携	テンプレートを見ながら作成しやすい	CLIと併用すると変更元が分かれやすい
C3 + Wrangler	開発・継続公開	コードと設定をGitで管理しやすい	Node.jsとターミナル操作が必要
Temporary deploy	一時プレビュー	アカウント接続前に公開URLを試せる	恒久運用にはclaimが必要

本記事ではC3 + Wranglerを選びます。Xでは、Kyraa氏がwrangler deploy --temporaryによる一時公開を紹介した投稿があり、公式にもTemporary preview accountsの手順があります。試作やAIエージェントからのプレビューには便利ですが、所有するアカウントへclaimして運用へ移す必要があります。最初から継続公開が目的なら、通常のプロジェクトを作成してください。

作成経路は途中で混ぜないことも大切です。Dashboardでコードを直したあと手元の古いファイルをデプロイすると、画面側の変更を上書きする可能性があります。CLIを選んだら、コードと設定は手元のGitを正として更新し、Dashboardは状態・ログ・設定結果の確認に使うと変更履歴を追いやすくなります。

Node.jsとWranglerを準備する

WranglerはWorkersのローカル開発、ログイン、設定、デプロイを行う公式CLIです。Cloudflare公式の導入資料は、Node.jsの最新LTSを推奨し、Wranglerをプロジェクトごとにローカル導入する方法を案内しています。古い記事にあるNode.jsの固定バージョンをそのまま入れるのではなく、現在サポートされるLTSを選びます。

まずターミナルでNode.jsとnpmが使えるか確認します。コマンドが見つからない場合は、Node.js公式サイトやバージョン管理ツールからLTSを導入してください。グローバルにWranglerを1つだけ入れるより、プロジェクトのdevDependenciesへ固定した方が、別プロジェクトの更新で急に挙動が変わる事故を減らせます。

node --version
npm --version
npx wrangler --version

すでに古いWranglerを使っている場合は、対象プロジェクト内でnpm install --save-dev wrangler@latestを実行し、再びバージョンを確認します。会社PCではNode.jsの導入やブラウザ認証が制限される場合があるため、先に社内ルールを確認してください。CloudflareのAPI Tokenを誰かから受け取って共有するのではなく、自分の権限でログインできる状態を整えます。

準備完了の基準

Node.jsとnpmのバージョンが表示される
最新のWranglerをプロジェクト単位で使える
Cloudflareアカウントへ自分でログインできる
Gitで管理する作業フォルダを決めた

C3でHello Worldプロジェクトを作る

C3はCreate Cloudflare CLIの略で、質問に答えるとWorkersプロジェクトの土台を作ります。Cloudflare公式のCLI入門に沿い、最初はHello World、Worker only、JavaScriptを選ぶと構成が小さくなります。TypeScriptに慣れている方はTypeScriptでも構いません。デプロイするか聞かれたら、まずNoを選び、ローカル確認を先に行います。

npm create cloudflare@latest -- my-first-worker
cd my-first-worker

作成後は主にsrc/index.js、wrangler.jsonc、package.json、lockファイルができます。src/index.jsが処理本体、wrangler.jsoncがWorker名、入口、compatibility date、Bindingsなどの設定、package.jsonが開発コマンドと依存関係です。分からない設定を増やす前に、各ファイルがどの役割かを確認します。

Xでは、ma2no4413氏が公式デモから移したDurable Objects、migrations、nodejs_compatなどを精査し、自分の実装には不要だったと振り返っています。高度なサンプルの設定は、そのサンプルが使う機能のためにあります。エラーを避ける目的で設定を丸ごとコピーすると、不要なBindingやmigrationが新たなエラー源になります。Hello Worldで生成された最小状態を基準にしてください。

wrangler devでローカル確認する

プロジェクトのフォルダでnpx wrangler devを実行すると、通常はhttp://localhost:8787でWorkerを確認できます。コードを保存すると再読み込みされるため、レスポンス本文を少し変え、ブラウザとターミナルの両方で結果を見ます。エラーが出たら、最初の赤い行だけでなく、ファイル名と行番号、直前の変更を記録してください。

npx wrangler dev

# 別のターミナルで確認
curl http://localhost:8787

Cloudflare公式のローカル開発資料によると、WranglerはworkerdとMiniflareを使い、コードとBindingsを既定ではローカルで動かします。KV、D1、R2などにremote: trueを付けると実際のリモート資源へ接続でき、本番データの変更や費用発生につながる可能性があります。必要なら本番とは別のstaging資源を用意し、書き込み処理を確認します。

localhostで動くことは、インターネットへ安全に公開できることと同じではありません。Xでは、小路氏がCodexでサイトを公開した過程を振り返り、ローカルから公開へ進むとCloudflare、DNS、Worker、DB、Secrets、CLIの理解が必要になったと投稿しています。ここで機能を増やさず、次章の6項目を1つずつ確認してから公開します。

Cloudflare Workersを安全に公開する手順

ローカル確認が終わったら、公開設定を最小限に整えます。最初の公開先はworkers.devで構いませんが、Secretをコードへ書かないこと、不要なBindingを増やさないこと、ログを見られることが条件です。独自ドメインはworkers.devの疎通後に設定し、RouteではDNSレコードも同時に確認します。

wrangler.jsoncとcompatibility_dateを確認する

wrangler.jsoncでは、少なくともWorker名を示すname、入口ファイルのmain、互換性を決めるcompatibility_dateを確認します。Worker名はworkers.devのURLにも使われます。Cloudflare公式では英数字とハイフンを使い、63文字以内、先頭と末尾をハイフンにしない規則があります。公開後に名前を変えるとURLも変わるため、短く説明できる名前にします。

compatibility dateは単なる記録日ではなく、Runtimeの挙動を段階的に切り替える値です。Cloudflare公式のNode.js互換資料では、2026年8月4日以降の日付を設定した新しいWorkerはNode.js互換とv2が既定で有効になり、設定ファイルのnodejs_compatを省略できると説明しています。2024年9月23日から2026年8月3日までの日付では、互換フラグが必要な構成があります。

Xでも、Masahiko Sakakibara氏がcompatibility dateとNode.js互換v2の関係を訂正した投稿があります。古い記事の設定を貼る前に、プロジェクトの日付と公式資料の更新日を見てください。なお、互換モードが有効でもNode.jsの全APIや全npmパッケージが完全に動くとは限りません。使用パッケージはwrangler devとデプロイ後の両方で検証します。

公開前に見る設定

name: URLと管理画面で識別できる名前
main: 実在する入口ファイル
compatibility_date: 現行挙動を確認した日付
Bindings: 実際に使う資源だけ
環境別設定: productionとstagingを混同しない

変数・Secrets・Bindingsを分ける

設定値は、公開されても問題のない通常変数、外部に出してはいけないSecrets、Cloudflare資源を接続するBindingsに分けます。環境名、機能フラグ、公開URLなどは通常変数、APIキー、パスワード、認証トークンはSecretです。KV、D1、R2、Queues、Durable ObjectsなどはBindingとしてWorkerから参照します。すべてを環境変数と呼んで一括管理しない方が安全です。

Cloudflare公式のSecrets資料は、機密情報を通常のvarsへ保存せずSecretを使うよう案内しています。公開環境へ登録するときは、値を設定ファイルへ直接書かず、次のコマンドで対話的に入力します。ローカルでは.dev.varsまたは.envのどちらか一方を使い、両方を混在させません。

npx wrangler secret put API_KEY

.dev.varsと.envはGitへコミットしないよう、.gitignoreへ登録します。値を一度でもGitHubへpushした場合、ファイルを削除するだけでは漏えい対応になりません。該当キーを無効化して再発行し、利用ログも確認します。Bindingを追加したときは、ローカル用と公開用が同じ資源を向いていないか、書き込み権限が必要最小限かも確認してください。

秘密情報の最低ルール

コード、通常変数、スクリーンショットへ値を書かない
wrangler secret putで公開環境へ登録する
ローカルファイルはGitの対象外にする
productionとstagingのキーを分ける
漏えい時は削除ではなく失効・再発行する

wrangler deployでworkers.devへ公開する

設定を確認したら、npx wrangler deployを実行します。初回はブラウザが開いてCloudflareへのログインと権限確認を求められます。完了すると通常はWorker名.アカウントサブドメイン.workers.dev形式のURLが表示されます。そのURLをブラウザとcurlで開き、本文、HTTPステータス、レスポンスヘッダーを確認します。

npx wrangler deploy

# 表示されたURLで確認
curl -i https://your-worker.your-subdomain.workers.dev

Cloudflare公式のworkers.dev資料によると、workers.devは公開URLであり、素早い開始や趣味の利用に向きます。初めてアカウントのworkers.devサブドメインを作成した直後は、反映まで約1分かかり、一時的に523が出る場合があります。数分待っても直らなければ、Worker名、サブドメイン、デプロイ結果、Cloudflare Statusを確認します。

Xでは、Abhijith氏が初めてWorkersとPagesを使い、難しい設定を予想したものの構築から公開までの流れが素直で、ゼロから約5時間で到達した事例を投稿しています。また、Tyler氏は別サービスで設定に時間を使った後、単純なポートフォリオがCloudflareでは動いたという体験を公開しています。いずれも個人の構成に限られますが、初回の範囲を小さくする価値を示します。

AIに実装を任せる場合も権限と設定は必要です。Khalid Warsame氏はClaude CodeがGitHub Profile Statsを実装・公開するPRを作った事例を公開していますが、既存のWorkers、Pages、KV構成に沿った作業でした。AIがURLを返したから完成とせず、どのアカウント、環境、Secret、Bindingへ公開したかを人が確認してください。

Custom DomainとRouteを使い分ける

workers.devで動作を確認したら、運用環境ではCustom DomainまたはRouteを検討します。Cloudflare公式のRouting資料は、Worker自体がWebサイトやAPIのオリジンになる場合はCustom Domain、既存サーバーへ届く前に一部リクエストを処理する場合はRouteを使うよう整理しています。workers.devは試用や趣味向けで、運用には独自の経路が推奨されます。

公開先	選ぶ状況	例	確認点
workers.dev	最初の疎通・試用	Hello World、個人試作	公開URLであること
Custom Domain	Workerが処理の起点	api.example.com	既存の同名DNSと競合しないこと
Route	既存オリジンの前で実行	example.com/api/*	Proxied DNSレコードがあること

Custom Domainは対象ホスト名の証明書とDNSをCloudflareが管理し、Workerがオリジンとして応答します。RouteはURLパターンに一致した通信をWorkerへ送り、必要なら既存オリジンへ続けます。RouteにはCloudflareで有効なゾーンと、オレンジ雲のProxied DNSレコードが必要です。レコードが存在しなければERR_NAME_NOT_RESOLVEDとなり、Workerのコードを直しても解決しません。

Routeを作る前に、対象ホスト名がCloudflare DNSで正しく名前解決し、Proxy statusがProxiedかを確認してください。ワイルドカードを広くしすぎると、管理画面、静的ファイル、決済通知など想定外の通信までWorkerを通します。まずexample.com/api/testのような狭いパスで検証し、ログを見てから範囲を広げます。DNSの見方はCloudflareでDNS設定する方法と注意点で確認できます。

Logs・rollback・無料上限を確認する

公開直後は、正常な1回だけでなく、存在しないパス、想定外のHTTPメソッド、外部APIの失敗も試します。Cloudflare公式のWorkers Logs資料では、呼び出しログに加え、コードのconsole.logなどを確認できます。個人情報、Authorizationヘッダー、APIキーをそのままログへ出さず、リクエストID、処理時間、結果区分など調査に必要な項目だけを記録します。

問題のあるバージョンを公開した場合は、修正を急いで重ねる前にrollbackを検討します。公式のrollback資料ではwrangler rollbackで以前のバージョンへ戻せます。ただし、KV、D1、R2、Durable Objectsなど外部資源のデータ変更やschema変更は戻りません。デプロイ前にバックアップやmigrationの戻し方を別に用意します。

npx wrangler rollback

2026年8月24日時点のCloudflare公式Limitsでは、Workers Freeは1日100,000リクエスト、1リクエスト10msのCPU時間、128MBメモリなどの上限があります。日次リクエストは午前0時UTCにリセットされます。無料だから無制限ではなく、CPUを多く使う変換や急なアクセス増ではエラーになり得ます。料金と超過時の判断は次回の記事で詳しく扱います。

公開前の最終チェック10項目

Workerの目的を1文で説明できる
wrangler devで正常系と異常系を確認した
name、main、compatibility_dateを確認した
不要な設定とBindingsを入れていない
秘密情報をSecretへ移し、Gitに含めていない
productionとstagingの資源を分けた
workers.devでステータスと本文を確認した
Custom DomainまたはRouteを用途で選んだ
Logsを確認し、rollbackの限界を理解した
無料枠のリクエスト・CPU・メモリ上限を確認した

Cloudflare Workersの始め方は、C3で最小構成を作り、ローカル、workers.dev、独自ドメインの順に公開範囲を広げることです。最初から高度なサンプルをコピーせず、compatibility date、Secrets、Bindings、DNS、Logs、Limitsを1つずつ確認すれば、失敗した場所を追いやすくなります。今日の一歩としてHello Worldを作成し、localhostとworkers.devで同じ応答が返るところまで進めてください。