初めてのWorkers開発（Hello Worldからデプロイまで）

《 Cloudflare完全ガイド目次へ》

ここまでの3ページは、既にあるものを守る話でした。ここからは自分でものを作る話に移ります。

第5章のCloudflare Workersで、エッジで動くサーバーレスの仕組みを説明しました。このページでは実際にコードを書き、世界中のCloudflareのネットワークに配置します。所要時間は5分ほどで、費用はかかりません。

サーバーを借りる必要も、OSを選ぶ必要も、証明書を用意する必要もありません。コマンドを2つ叩けば、あなたのコードは世界300以上の都市で動き始めます。この体験は、一度やってみる価値があります。

このページで分かること
準備するもの
手順1：プロジェクトを作る
1. 作られたファイル
手順2：ローカルで動かす
手順3：世界中にデプロイする
1. 無料でどこまで使えるか
手順4：設定ファイルを読む
1. compatibility_date とは何か
手順5：独自ドメインを割り当てる
少し実用的なコードにしてみる
秘密情報の扱い方
ログを見る
ここから先の広がり
初心者が注意するポイント
関連サービス
まとめ
次に読む

このページで分かること

Workersの開発に必要な準備（Node.jsとWrangler）
プロジェクトを作り、ローカルで動かす手順
世界中にデプロイするコマンドと、公開されるURL
設定ファイル wrangler.jsonc の読み方
独自ドメインの割り当て方と、秘密情報の扱い方

準備するもの

必要なのは2つだけです。

Cloudflareアカウント（無料。すでに作ってあればそれで構いません）
Node.js（バージョン16.17.0以降）

Node.jsが入っているかは、ターミナルで次のコマンドを実行すれば分かります。

node -v

v20.11.0 のようにバージョンが表示されれば大丈夫です。「コマンドが見つかりません」と出たら、Node.jsの公式サイトからLTS版を入れてください。

ドメインは不要です。 最初はCloudflareが用意する workers.dev のURLで動かせます。独自ドメインを割り当てるのは、このページの後半で扱います。

手順1：プロジェクトを作る

ターミナルで、作業したいフォルダに移動して、次のコマンドを実行します。

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

my-first-worker の部分がプロジェクト名兼フォルダ名です。好きな名前で構いません（英数字とハイフンのみ）。

このコマンドは C3（create-cloudflare CLI） と呼ばれるもので、雛形の作成からデプロイまでを一括で面倒みてくれます。実行すると、いくつか質問されます。

質問	選ぶもの
What would you like to start with?	`Hello World example`
Which template would you like to use?	`Worker only`
Which language do you want to use?	`JavaScript`
Do you want to use git for version control?	`Yes`
Do you want to deploy your application?	`No`（まずローカルで確認するため）

TypeScriptを選んでも構いませんが、初回はJavaScriptのほうが余計な要素が減って読みやすくなります。

作られたファイル

処理が終わると、my-first-worker フォルダに次のものができています。

my-first-worker/
├── src/
│   └── index.js        ← あなたのコード
├── wrangler.jsonc      ← 設定ファイル
├── package.json
└── node_modules/

src/index.js の中身は、これだけです。

export default {
    async fetch(request, env, ctx) {
        return new Response("Hello World!");
    },
};

この短さがWorkersの本質です。 リクエストが来たら fetch が呼ばれ、返した Response がそのまま応答になります。サーバーの起動処理も、ポートの待ち受けも、ルーティングの枠組みもありません。

3つの引数の意味は次のとおりです。

request：届いたリクエスト。URL、メソッド、ヘッダー、本文が入っています
env：バインディングでつながった外部リソース（KV・D1・R2など）と、環境変数
ctx：実行の制御。応答を返したあとに処理を続ける waitUntil などが使えます

手順2：ローカルで動かす

プロジェクトのフォルダに移動して、開発サーバーを起動します。

cd my-first-worker
npx wrangler dev

http://localhost:8787 が表示されるので、ブラウザで開いてください。「Hello World!」と表示されれば成功です。

ここで重要なのは、これが単なるNode.jsのエミュレーションではないことです。Wranglerは、Cloudflareの本番環境と同じworkerdというランタイムをローカルで動かしています。つまり、ここで動けば本番でもほぼそのまま動きます。

src/index.js を編集して保存すると、自動で反映されます。試しに文字列を変えてみてください。

return new Response("こんにちは、Workers！");

日本語が文字化けする場合は、文字コードを明示します。

return new Response("こんにちは、Workers！", {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
});

終了するときは Ctrl + C です。

手順3：世界中にデプロイする

いよいよ本番です。次のコマンドを実行します。

npx wrangler deploy

初回は、ブラウザが開いてCloudflareアカウントとの連携を求められます。許可すると、ターミナルに戻ってデプロイが進みます。

数秒後、次のようなURLが表示されます。

https://my-first-worker.あなたのサブドメイン.workers.dev

このURLを開いてください。世界中どこからでも、そのコードが動きます。

この数秒の間に起きたことを整理しておきます。

コードがCloudflareにアップロードされた
世界300以上の都市のサーバーに配布された
HTTPSの証明書が自動で用意された
DNSの設定が自動で行われた
誰がアクセスしても、その人に最も近い場所で実行されるようになった

サーバーを1台も借りず、OSを1つも選ばず、証明書を1枚も申請していません。これがサーバーレスであり、エッジで動くということです。

無料でどこまで使えるか

デプロイした時点では課金は発生していません。無料枠は次のとおりです。

項目	Freeプラン
リクエスト数	1日10万回
CPU時間	1リクエストあたり10ミリ秒
Worker数	100個

個人の実験や小さなツールなら、これで十分足ります。詳しくはWorkersのページを参照してください。

手順4：設定ファイルを読む

wrangler.jsonc を開くと、最低限これだけが書かれています。

{
  "name": "my-first-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-08-20"
}

name：Workerの名前。workers.dev のURLの一部になります
main：入口となるファイル
compatibility_date：これが重要です

compatibility_date とは何か

compatibility_date は、どの時点のランタイムの挙動で動かすかを固定するものです。

Cloudflareは日々ランタイムを改善しています。中には、既存の動作を変えてしまう修正も含まれます。もし常に最新の挙動が適用されると、あなたが何も触っていないのに、ある日突然Workerの動きが変わることになります。

compatibility_date を書いておくと、その日付時点の挙動が保たれます。新しい機能を使いたくなったら、日付を進めて、テストして、デプロイする――このタイミングを自分で選べるわけです。

なお設定ファイルの形式は、新規プロジェクトでは wrangler.jsonc が推奨されています。従来の wrangler.toml も引き続き使えますが、新しい機能の一部はJSON形式のみで提供されます。

手順5：独自ドメインを割り当てる

workers.dev のURLは便利ですが、実際に公開するなら独自ドメインを使いたくなります。

Cloudflareで管理しているドメインであれば、設定ファイルに数行足すだけです。

{
  "name": "my-first-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-08-20",
  "routes": [
    { "pattern": "api.example.com", "custom_domain": true }
  ]
}

保存して npx wrangler deploy を実行すると、DNSレコードも証明書も自動で用意されます。自分でCNAMEを書く必要も、証明書を申請する必要もありません。

サイトの一部だけをWorkerに担当させることもできます。

"routes": [
  { "pattern": "example.com/api/*", "zone_name": "example.com" }
]

この書き方だと、example.com/api/ 以下だけがWorkerに渡り、それ以外は通常どおり元のサーバーへ流れます。既存サイトに手を入れずに、一部の機能だけをエッジに移せるわけです。

少し実用的なコードにしてみる

Hello Worldのままでは面白くないので、URLによって応答を変えてみます。

export default {
    async fetch(request, env, ctx) {
        const url = new URL(request.url);

        if (url.pathname === "/time") {
            return Response.json({
                now: new Date().toISOString(),
                colo: request.cf?.colo,
                country: request.cf?.country,
            });
        }

        if (url.pathname === "/hello") {
            const name = url.searchParams.get("name") ?? "世界";
            return new Response(`こんにちは、${name}！`, {
                headers: { "Content-Type": "text/plain; charset=utf-8" },
            });
        }

        return new Response("Not Found", { status: 404 });
    },
};

/time にアクセスすると、時刻と一緒に colo（どの都市のデータセンターで実行されたか）と country（アクセス元の国）が返ります。request.cf は、Cloudflareがリクエストに付けてくれる情報で、これがエッジで動いていることの何よりの証拠になります。

スマートフォンのモバイル回線からアクセスすると、colo の値が変わることがあります。同じコードが、アクセスする人ごとに違う場所で動いていることを実感できるはずです。

秘密情報の扱い方

APIキーなどをコードに直接書いてはいけません。Gitに入り、公開されてしまいます。

npx wrangler secret put API_KEY

このコマンドを実行すると値の入力を求められ、Cloudflare側に暗号化されて保存されます。コードからは env.API_KEY で読めます。

export default {
    async fetch(request, env, ctx) {
        const key = env.API_KEY;   // 設定ファイルにもGitにも残らない
        // ...
    },
};

秘密でない設定値（動作モードなど）は、設定ファイルの vars に書いても構いません。

ログを見る

デプロイしたWorkerが本番で何をしているかは、次のコマンドで見られます。

npx wrangler tail

実行したまま本番URLにアクセスすると、console.log の内容やエラーがリアルタイムで流れてきます。サーバーにSSHで入ってログファイルを追う代わりがこれです。

アクセス数が多いWorkerでは、一部が間引かれる（サンプリングされる）ことがあります。

ここから先の広がり

Hello Worldが動いたら、env を通じて他のサービスとつなげます。

Workers KV：設定値やカウンタを保存する
D1：SQLでデータを扱う
R2：画像やファイルを置く
Workers AI：AIモデルを呼び出す
Durable Objects：状態を持たせる

つなぎ方はどれも同じ形です。設定ファイルにバインディングを書き、コードから env.〇〇 で使う――これだけです。接続文字列も、認証情報も、ネットワーク設定も出てきません。

初心者が注意するポイント

wrangler deploy は即座に本番反映される：確認画面はありません。試すときは名前を分けるか、環境機能を使ってください
CPU時間10ミリ秒の意味を誤解しない：これは「計算していた時間」であり、外部APIの応答を待っている時間は含まれません。無料枠で足りなくなるのは、重い計算をした場合だけです
npx を付ける理由：プロジェクトにインストールされたWranglerを使うためです。グローバルインストールしたものと混ざると、バージョン違いで動かないことがあります
node_modules はGitに入れない：C3が作る .gitignore に既に書かれています。消さないでください
秘密情報を vars に書かない：vars は設定ファイルに平文で残ります。APIキーは必ず secret put を使ってください
ローカルで動いたら本番でもほぼ動く：ただしバインディング先（KVやD1）はローカルと本番で別物です。データが空なのは正常です
最初のWorkerは消してよい：npx wrangler delete で削除できます。実験用を残し続けると、Worker数の上限（Free 100個）を圧迫します

まとめ

必要なのはCloudflareアカウントとNode.js（16.17.0以降）だけ。ドメインは無くても始められる
npm create cloudflare@latest -- my-first-worker で雛形ができる
npx wrangler dev でローカル起動。本番と同じworkerdランタイムが動くため、ここで動けば本番でも動く
npx wrangler deploy で世界300都市以上に配布され、HTTPSも自動で用意される
compatibility_date は、ランタイムの挙動を固定するための日付。勝手に動作が変わるのを防ぐ
新規プロジェクトの設定ファイルは wrangler.jsonc が推奨
独自ドメインは routes に custom_domain: true を書くだけ。DNSも証明書も自動
秘密情報は wrangler secret put、本番のログは wrangler tail
他サービスとの接続はすべて env.〇〇 の形に統一されている

コマンド2つで世界中にコードが配られる――この手応えが、Cloudflareの開発プラットフォームを使う一番の理由です。

次のページでは、コードではなくサイトそのものを公開します。HTMLファイル一式や、静的サイトジェネレーターで作ったサイトを、Cloudflareで公開する手順です。

次に読む

→ ガイドの目次に戻る

※本記事の情報は 2026年8月時点のものです。