結論
Cloudflare Workers は、Cloudflare の世界中のデータセンターで JavaScript・TypeScript・Python・Rust などのコードを動かすサーバーレスの実行環境です。無料プランは1日10万リクエストまで、有料プランは月5ドルからで、Wrangler(公式の CLI)の wrangler dev を使えばログインせずに手元で動かせます。
この記事でわかること
- 料金・無料枠の上限と、公式の価格例5つを Python で検算した結果
- wrangler dev で動かした Worker の curl の応答と、KV・D1 をローカルで使った実物
- Error 1027・1102 や Address already in use など、つまずきの原文と直し方
Worker は、利用者に近いデータセンターでリクエストを受け取り、fetch ハンドラーで応答を作ります。必要なら KV・D1・R2 などのデータ置き場や、元のサーバー(オリジン)に問い合わせます。
flowchart TD
U[ブラウザ・アプリ] --> E[近くのデータセンター]
E --> W[Worker の fetch ハンドラー]
W -->|必要なら| S[(KV・D1・R2<br>元のサーバー)]
S --> W
W --> R[応答を返す]
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| Cloudflare Workers とは | Cloudflare のネットワーク上でコードを動かすサーバーレスの実行環境 | Cloudflare Workersとは |
| 無料でどこまで使えるか | 1日10万リクエスト、1回あたり CPU 時間10ミリ秒まで | 料金 |
| 有料プランの料金 | 月5ドルから。月1,000万リクエストと CPU 3,000万ミリ秒を含む | 料金 |
| 使い方の最初の一歩 | npm create cloudflare@latest で作り、npx wrangler dev で動かす |
始め方 |
| ログインせずに試せるか | ローカル実行・型の生成・--dry-run はログインなしで動いた |
wrangler dev |
| 対応言語 | JavaScript・TypeScript・Python・Rust。ほかは WebAssembly 経由 | Cloudflare Workersとは |
| Pages との違い | 公式は新しいプロジェクトを Workers で始めるよう案内している | Pagesとの違い |
| 上限を超えたとき | 無料の1日上限は Error 1027、CPU・メモリ超過は Error 1102 | 上限とエラー |
確認環境:Ubuntu 24.04(glibc 2.39)の上で、Node.js 22.23.4・npm 10.9.9 を使い、作業用のフォルダーに npm i -D wrangler@latest で Wrangler 4.164.0 を入れました(workerd 1.20261117.1 が一緒に入りました)。npx wrangler dev --ip 127.0.0.1 --port 8787 で小さな Worker を手元だけで起動し、curl 8.5.0 と Python 3 の urllib で応答・ヘッダー・応答時間を確かめています。KV・D1 はローカルのシミュレーション、Cron は手元の呼び出し用の URL で動かしました。Cloudflare にはログインせず、デプロイもしていません(wrangler whoami で未ログインであることを確かめ、wrangler deploy --dry-run まで)。外のネットワークに出ない状態で動かしたため、Request.cf の取得に失敗する警告が出ています。npm create cloudflare(C3)の対話、本番での動作、ダッシュボードの画面、Python Workers は実行しておらず、Cloudflare の公式ドキュメント(developers.cloudflare.com)と公式ブログで確かめた内容です。料金の試算は公式の単価を使って Python で計算しました(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Cloudflare Workersとは|使い方・料金・無料枠を手元で実演」
Cloudflare Workersとは(意味・仕組み・対応言語)
この節では、Cloudflare Workers が何で、どういう仕組みで動くのかが分かります。
Cloudflare Workers は、Cloudflare のグローバルなネットワークの上でアプリを作り、配置し、規模を広げられるサーバーレスの実行環境です。サーバーの用意や OS の更新は Cloudflare 側が受け持ち、書くのはリクエストを受けて応答を返すコードだけです。
動かしているのは、Cloudflare がオープンソースで公開している実行環境 workerd です。公式のローカル開発の説明には、wrangler dev も内部の Miniflare を通じて手元の workerd でコードを動かし、この workerd は本番の Workers でも使われている、と書かれています。手元で起動したときのプロセスを見ると、実際に workerd serve が 127.0.0.1 のポートで待ち受けていました。
LISTEN 127.0.0.1:8787 users:(("workerd",pid=9912,fd=13))
LISTEN 127.0.0.1:9229 users:(("workerd",pid=9912,fd=14))
LISTEN 127.0.0.1:42087 users:(("node",pid=9870,fd=24))
8787 が Worker の入口、9229 はデバッガー(DevTools)用の口です。どちらも 127.0.0.1 だけで待ち受けていて、同じ LAN の別の PC からは見えません。
対応言語
公式の「Languages」のページは、JavaScript・TypeScript・Python・Rust を第一級の言語として挙げています(Rust の項目にはベータの表示があります)。それ以外の C・C++・Kotlin・Go などは、WebAssembly(Wasm)にコンパイルして動かせます。Python Workers は、2026年9月21日の Cloudflare の公式ブログで一般提供(GA)になったと発表されました。WebAssembly の仕組みはWebAssembly(Wasm)とは|仕組みとJSとの速度を実測で扱っています。
Cloudflare Workersでできること・向いている処理
この節では、Workers で作れるものと、向いている処理・向かない処理が分かります。
1API・Webhook の受け口
JSON を受けて返す小さな API、外部サービスからの通知を受けて形を変える処理。D1 や KV と組み合わせると、データを持つ API になる。
2元のサーバーの前に立つ処理
ルート(Routes)で URL の一部に Worker を割り当て、ヘッダーの付け替え・リダイレクト・振り分けを元のサーバーに届く前に行う。
3サイト全体の配信
静的アセット(Static Assets)で HTML・CSS・画像を Worker と一緒に配信する。静的アセットへのリクエストは無料・無制限と料金のページにある。
このほか、決まった時刻に処理を動かす Cron Triggers、キュー(Queues)、AI のモデルを呼ぶ Workers AI なども同じ Worker から使えます。
向き・不向きは上限から読み取れます。無料プランは1回あたり CPU 時間10ミリ秒、有料でも既定30秒(最大5分)、メモリは1つの Worker で128MB です。外部の API やデータベースの応答を待つ時間は CPU 時間に数えられないので、待ち時間が長くても計算が軽い処理(中継・変換・振り分け)に向きます。大きなファイルの変換や長い計算のように CPU を使い続ける処理は、上限と料金の両方で不利になります。
Cloudflare Workersの料金(無料プラン・有料プラン)
この節では、Workers の料金と無料枠、公式の価格例を Python で検算した結果が分かります。
以下は 2026年11月18日時点の公式の料金ページ(最終更新 2026年11月13日)の値です。料金は変わることがあるので、使う前に公式のページを確かめてください。
| 項目 | Workers Free | Workers Paid(Standard) |
|---|---|---|
| 基本料金 | 0ドル | アカウントあたり月5ドルから |
| リクエスト | 1日10万 | 月1,000万を含む。超過は100万あたり0.30ドル |
| CPU 時間 | 1回あたり10ミリ秒 | 月3,000万ミリ秒を含む。超過は100万ミリ秒あたり0.02ドル |
| 1回の CPU 時間の上限 | 10ミリ秒 | 既定30秒・最大5分 |
| 静的アセット | 無料・無制限 | 無料・無制限 |
| Workers Logs | 1日20万件・3日保存 | 月2,000万件を含む・7日保存 |
実行時間(Duration)は課金されず、数えるのは CPU 時間です。Worker から外へのサブリクエストも課金の対象外と書かれています。Workers Logs は 2026年12月1日から Cloudflare Observability の料金体系に移る予定、という注記もありました。
公式の価格例を Python で検算する
料金のページには価格例が5つ載っています。上の単価で式を作り、同じ結果になるかを確かめました。
def cost(req, cpu_ms_avg, static=0, cpu_total=None):
dyn = req - static # 静的アセットは数えない
base = 5.0
r = max(0, dyn - 10_000_000) / 1e6 * 0.30
cpu = cpu_total if cpu_total is not None else dyn * cpu_ms_avg
c = max(0, cpu - 30_000_000) / 1e6 * 0.02
return base, round(r, 2), round(c, 2), round(base + r + c, 2)
print(cost(15_000_000, 7)) # 例1
print(cost(15_000_000, 7, static=12_000_000)) # 例2
print(cost(720, 0, cpu_total=720 * 180_000)) # 例3 毎時の Cron
print(cost(100_000_000, 7)) # 例4
print(cost(100_000_000, 7, cpu_total=100_000_000 * 0.2 * 7)) # 例5 キャッシュ80%
(5.0, 1.5, 1.5, 8.0)
(5.0, 0.0, 0.0, 5.0)
(5.0, 0.0, 1.99, 6.99)
(5.0, 27.0, 13.4, 45.4)
(5.0, 27.0, 2.2, 34.2)
5つとも公式の合計(8.00ドル・5.00ドル・6.99ドル・45.40ドル・34.20ドル)と一致しました。例5は Workers Caching でキャッシュから返った分も1リクエストとして数え、CPU 時間はキャッシュに無かった分だけ数える、という公式の説明どおりに計算しています。
同じ式で、月のリクエスト数と平均 CPU 時間を変えた試算です(有料プラン、静的アセットなし)。
| 月のリクエスト | 平均2ミリ秒 | 平均5ミリ秒 | 平均10ミリ秒 |
|---|---|---|---|
| 300万 | 5.00ドル | 5.00ドル | 5.00ドル |
| 1,000万 | 5.00ドル | 5.40ドル | 6.40ドル |
| 3,000万 | 11.60ドル | 13.40ドル | 16.40ドル |
| 5,000万 | 18.40ドル | 21.40ドル | 26.40ドル |
| 1億 | 35.40ドル | 41.40ドル | 51.40ドル |
| 3億 | 103.40ドル | 121.40ドル | 151.40ドル |
無料プランの1日10万は、30日で300万リクエスト、平均すると1秒に約1.16回です。1日の上限は UTC の0時(日本時間の午前9時)に戻ります。アクセスが特定の時間に集中するサイトでは、月の合計が300万より少なくても、その日の上限に先に届くことがあります。
KV・D1・R2 の無料枠
| 製品 | 無料の範囲(公式の記載) | 有料の主な単価 |
|---|---|---|
| Workers KV | 1日に読み取り10万・書き込み1,000、保存1GB | 書き込みは月100万を超えると100万あたり5.00ドル |
| D1 | 1日に読み取り500万行・書き込み10万行、保存5GB | 保存は5GBを超えると GB・月あたり0.75ドル |
| R2 | 月10GB・Class A 100万・Class B 1,000万 | Standard の保存は GB・月あたり0.015ドル。外への転送は無料 |
| Queues | 1日1万オペレーション | 月100万を超えると100万あたり0.40ドル |
無料プランの上限と、超えたときのエラー(1027・1102)
この節では、Workers の主な上限と、上限を超えたときに何が返るのかが分かります。
| 上限 | Free | Paid |
|---|---|---|
| 1日のリクエスト | 10万 | 無制限 |
| メモリ | 128MB | 128MB |
| サブリクエスト(1回あたり) | 50 | 1万 |
| 同時の外向き接続(1回あたり) | 6 | 6 |
| 環境変数の数 | 64 | 128 |
| Worker の大きさ(圧縮前) | 64MiB | 64MiB |
| 起動時間 | 1秒 | 1秒 |
| Worker の数 | 100 | 500 |
| Cron Triggers | アカウントあたり5 | アカウントあたり250 |
URL は16KB、リクエストヘッダーとレスポンスヘッダーはそれぞれ合計128KB までです。リクエストボディの上限は Workers のプランではなくドメインの Cloudflare のプランで決まり(Free・Pro は100MB)、超えると 413 が返ります。
Error 1027(無料の1日上限)
Free で1日10万リクエストを超えたとき
ルートが Fail open なら Worker を飛ばして元のサーバーへ
Fail closed なら 1027 のエラーページを返す
Error 1102(資源の上限)
CPU 時間かメモリの上限を超えたとき
文言は「Worker exceeded resource limits」
記録では exceededCpu・exceededMemory
Fail open と Fail closed はルートの設定で選びます。公式は、セキュリティのために置いた Worker は Fail closed が合う、と説明しています。Worker を通らないと困る処理(認証の確かめなど)を Fail open にすると、上限を超えた時間帯はその処理が抜けた状態で元のサーバーに届きます。
Wranglerのインストールと始め方
この節では、公式の CLI である Wrangler の入れ方と、最初の Worker を作る手順が分かります。
Wrangler の公式ページは、プロジェクトごとにローカルに入れることを勧めています。チームで同じ版をそろえられ、プロジェクトごとに版を管理でき、前の版に戻すこともできるからです。対応する OS は macOS 13.5 以降・Windows 11・glibc 2.35 以降の Linux と書かれています。
Node.js を用意する
Wrangler は Node.js と npm で動く。公式は Current・Active・Maintenance の各版を対象にしている。この記事では Node.js 22.23.4 を使った。
プロジェクトを作る
公式の始め方では npm create cloudflare@latest -- my-first-worker を実行し、Hello World の例・Worker only・JavaScript を選ぶ。wrangler.jsonc・src/index.js・package.json ができる。
既存のフォルダーに入れる場合
npm i -D wrangler@latest で開発用の依存として入れる。版の確かめ方は npx wrangler --version。更新も同じ install のコマンドで行う。
手元で動かす
npx wrangler dev で起動し、http://localhost:8787 を開く。コードを保存すると自動で読み込み直される。
公開する
npx wrangler deploy で workers.dev のサブドメインかカスタムドメインに配置する。ここで Cloudflare のアカウントへのログインが要る。
手元では手順3の形で入れました。かかった時間と大きさは次のとおりです。
$ npm i -D wrangler@latest
added 38 packages, and audited 39 packages in 9s
$ npx wrangler --version
4.164.0
入れたあとの node_modules は 236MB で、そのうち 156MB が @cloudflare(workerd の実行ファイルを含む)でした。npm のキャッシュも 151MB できたので、容量の小さい環境ではキャッシュの置き場所に気をつけます。注意点として、Wrangler を入れていないフォルダーで npx wrangler を実行すると最新版が使われる、と公式に書かれています。チームで版をそろえるなら、package.json に入れて使います。
wrangler devでローカル実行する(実行結果)
この節では、wrangler dev で Worker を手元で起動し、curl で応答を確かめた実物が分かります。
使った設定ファイル wrangler.jsonc です。KV と D1 の id は手元だけで使う仮の値です。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "hello-worker",
"main": "src/index.js",
"compatibility_date": "2026-11-01",
"vars": { "GREETING": "こんにちは" },
"kv_namespaces": [{ "binding": "MY_KV", "id": "local-dummy-id" }],
"d1_databases": [{ "binding": "DB", "database_name": "t643-local",
"database_id": "00000000-0000-0000-0000-000000000000" }],
"triggers": { "crons": ["*/30 * * * *"] }
}
起動したときの表示です。どのバインディングが「local」で動いているかが一覧で出ます。シークレットの値は (hidden) と伏せられました。
$ npx wrangler dev --ip 127.0.0.1 --port 8787
⛅️ wrangler 4.164.0
────────────────────
Using secrets defined in .dev.vars
Your Worker has access to the following bindings:
Binding Resource Mode
env.MY_KV (local-dummy-id) KV Namespace local
env.DB (t643-local) D1 Database local
env.GREETING ("こんにちは") Environment Variable local
env.API_TOKEN ("(hidden)") Environment Variable local
[wrangler:warn] Unable to fetch the `Request.cf` object! Falling back to a default placeholder...
Error: getaddrinfo ENOTFOUND workers.cloudflare.com
⎔ Starting local server...
[wrangler:info] Ready on http://127.0.0.1:8787
Request.cf の警告は、国やデータセンターなどの情報が入る request.cf の見本を Cloudflare から取ろうとして、外に出られなかったために出たものです。代わりの値で起動は続き、以下の確認はすべてこの状態で動きました。ログインを求められることもありませんでした。
$ curl -si http://127.0.0.1:8787/
HTTP/1.1 200 OK
Content-Length: 14
Content-Type: text/plain;charset=UTF-8
Hello Worker!
$ curl -si -X POST http://127.0.0.1:8787/json
HTTP/1.1 200 OK
Content-Length: 62
Content-Type: application/json
{"greeting":"こんにちは","hasToken":true,"method":"POST"}
$ curl -si http://127.0.0.1:8787/nope
HTTP/1.1 404 Not Found
Content-Length: 10
Content-Type: text/plain;charset=UTF-8
Not Found
Response.json() で返すと Content-Type: application/json が自動で付き、文字列の new Response() では text/plain;charset=UTF-8 になりました。端末の側には、届いたリクエストが1行ずつ出ます。
[wrangler:info] GET / 200 OK (5ms)
[wrangler:info] POST /json 200 OK (4ms)
[wrangler:info] GET /kv 200 OK (10ms)
[wrangler:info] GET /nope 404 Not Found (4ms)
手元での応答時間
同じ PC から Python で200回ずつ順に送り、応答までの時間を測りました。手元の数字であり、本番の速さとは別のものです。
fetchハンドラーの書き方とCron(scheduled)
この節では、Worker の基本の形である fetch ハンドラーと、定期実行の scheduled ハンドラーの書き方が分かります。
Worker は ES モジュールの形で、export default のオブジェクトにハンドラーを並べます。fetch は HTTP のリクエストごとに呼ばれ、引数は request(届いたリクエスト)・env(環境変数やバインディング)・ctx(応答のあとも続ける処理などに使う)の3つです。上の確認で使ったコードの全体です。
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (url.pathname === "/") {
return new Response("Hello Worker!\n");
}
if (url.pathname === "/json") {
return Response.json({
greeting: env.GREETING,
hasToken: typeof env.API_TOKEN === "string",
method: request.method,
});
}
if (url.pathname === "/kv") {
const key = url.searchParams.get("key") ?? "count";
const now = Number((await env.MY_KV.get(key)) ?? "0") + 1;
await env.MY_KV.put(key, String(now));
return new Response(`${key}=${now}\n`);
}
if (url.pathname === "/notes") {
const { results } = await env.DB.prepare(
"SELECT id, body FROM notes ORDER BY id"
).all();
return Response.json(results);
}
if (url.pathname === "/error") {
throw new Error("わざと起こしたエラー");
}
return new Response("Not Found\n", { status: 404 });
},
async scheduled(controller, env, ctx) {
console.log("cron:", controller.cron);
},
};
/json ではシークレットの値そのものは返さず、「文字列として届いているか」だけを返しています。値を応答やログに出さない形にしておくと、確かめるときにも値が漏れません。
Cron Triggers を手元で動かす
scheduled は、設定ファイルの triggers.crons に書いた時刻に呼ばれます。公式によると、実行の時刻は UTC で数えます。日本時間の毎朝9時に動かしたいなら 0 0 * * * です。変更が全体に行き渡るまで最大15分かかり、その間は予定の実行が抜けることがある、とも書かれています。
手元では、公式が案内している URL で呼び出せました。
$ curl -si "http://127.0.0.1:8787/cdn-cgi/local/scheduled?cron=*/30+*+*+*+*&format=json"
HTTP/1.1 200 OK
Content-Length: 32
Content-Type: application/json
{"outcome":"ok","noRetry":false}
端末には cron: */30 * * * * と出て、controller.cron に指定したパターンが入っていました。なお、以前の版の解説で見かける --test-scheduled を付けた起動と /__scheduled の URL は、この版でも付けたときだけ動き(応答は Ran scheduled event)、付けないと 404 でした。いまの公式ページに載っているのは /cdn-cgi/local/scheduled のほうです。
環境変数とシークレット(vars・.dev.vars・secret put)
この節では、設定値と秘密の値をどこに置き、手元と本番でどう読み分けるのかが分かります。
設定値は wrangler.jsonc の vars に書き、コードでは env.GREETING のように読みます。秘密の値(API のトークンなど)はシークレットにします。公式の説明では、vars の値は暗号化されず Wrangler やダッシュボードで見えるのに対し、シークレットは設定したあと値が表示されません。Worker の側からはどちらも同じ env の値として届きます。
API のトークンを Worker に渡すとき
公式の注意:機密情報を vars に入れず、シークレットを使う
手元用の値は、設定ファイルと同じフォルダーの .dev.vars か .env に dotenv の形で書きます。この記事では仮の値を入れました。
# .dev.vars(手元だけで使う。Git に入れない)
API_TOKEN=dummy-local-only
公式に書かれている読み込みの決まりは次のとおりです。
.dev.varsと.envはどちらか一方を使う。.dev.varsがあると.envの値は読まれない- 環境ごとに
.dev.vars.<環境名>を作ると、そちらだけが読まれる .env系は重ねて読まれ、.env.<環境名>.local→.env.local→.env.<環境名>→.envの順に優先される.gitignoreに.dev.vars*と.env*を足すvarsは環境の間で引き継がれないので、env.<環境名>.varsに環境ごとに書く
本番のシークレットは npx wrangler secret put <KEY> で入れます。公式によると、このコマンドは新しい版を作ってすぐにデプロイします。段階的なデプロイを使っている場合は npx wrangler versions secret put <KEY> で版だけを作り、あとから wrangler versions deploy で出します。手元の起動で .dev.vars が見つからないときは、ログに「local dev variables file not found at ".dev.vars". Continuing...」と出て、そのまま起動しました。
KV・D1・R2などのバインディング(ローカルで動かした結果)
この節では、Workers からデータ置き場を使う「バインディング」の考え方と、KV・D1 を手元で動かした結果が分かります。
バインディングは、設定ファイルに書いた資源(KV の名前空間・D1 のデータベース・R2 のバケットなど)を、env.MY_KV のような名前でコードから使えるようにする仕組みです。鍵や接続文字列をコードに書かずに済みます。
| 名前 | 公式の説明 | 向いている用途(公式の例) |
|---|---|---|
| Workers KV | 結果整合性のキー・バリューの置き場 | 設定・振り分けの情報・A/B テスト。1つのキーへの書き込みは毎秒1回まで |
| D1 | Cloudflare のサーバーレスのデータベース(SQL) | ユーザー・商品・注文などの表のデータ。1つのデータベースは10GBまで |
| R2 | S3 互換のオブジェクトの置き場。外への転送料金なし | 画像・動画・アップロードされたファイル・ログ |
| Durable Objects | 一意の名前と、トランザクションのある置き場 | チャットなどの同時編集、強い一貫性が要る処理 |
| Queues | 届けることを保証するメッセージのキュー | あとで行う処理、Worker の間の受け渡し |
| Hyperdrive | MySQL・Postgres への問い合わせを速くする | 既存のデータベースに Worker からつなぐ |
KV を手元で動かす
/kv を3回呼ぶと、KV に入れた数が増えていきました。wrangler dev を止めて起動し直したあとも、続きの4から始まりました。手元のデータは、プロジェクトの中の .wrangler/state/v3/ の下(kv・d1・r2 などのフォルダー)に保存されていました。
$ curl -s "http://127.0.0.1:8787/kv?key=visits" # 3回
visits=1
visits=2
visits=3
(wrangler dev を止めて起動し直す)
$ curl -s "http://127.0.0.1:8787/kv?key=visits"
visits=4
手元の KV は1台の PC の中だけで動くので、本番の KV にある「書き込みが世界中に行き渡るまで、書き込む前の値が読めることがある」という結果整合性の性質は、手元では再現されません。数を数える用途は、本番では同じキーへの書き込みの上限(毎秒1回)にも当たります。数を正確に数えるなら D1 か Durable Objects を検討します。
D1 を手元で動かす
D1 は --local を付けると手元のデータベースに対して SQL を流せます。
$ npx wrangler d1 execute t643-local --local --file=schema.sql
Resource location: local
Use --remote if you want to access the remote instance.
🌀 Executing on local database t643-local (00000000-0000-0000-0000-000000000000) from .wrangler/state/v3/d1:
🌀 To execute on your remote database, add a --remote flag to your wrangler command.
$ curl -s http://127.0.0.1:8787/notes
[{"id":1,"body":"first"},{"id":2,"body":"second"}]
--remote を付けると本物のデータベースに流れます。手元で試すときは、表示の「Resource location: local」を見てから進めると、取り違えを防げます。公式の説明では、AI のバインディングだけは手元でもリモートで動き、それ以外のバインディングは手元でシミュレーションされます。バインディングごとに remote: true を付けると、その資源だけ本物につなげます(書き込みが本物のデータに入り、料金もかかる、と注意があります)。
型の生成(TypeScript)
npx wrangler types を実行すると、設定ファイルから env の型を作った worker-configuration.d.ts ができました(16,401行)。先頭はこうなっています。
interface __BaseEnv_Env {
MY_KV: KVNamespace;
DB: D1Database;
GREETING: "こんにちは";
API_TOKEN: string;
}
.dev.vars の API_TOKEN も型に入りました。設定ファイルを変えたら wrangler types を実行し直すよう、表示でも案内されます。
デプロイと公開の方法(workers.dev・ルート・カスタムドメイン)
この節では、Worker を公開する3つの方法の違いと、デプロイの前に確かめることが分かります。
デプロイは npx wrangler deploy です。公開先の URL は <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev の形で、公式の始め方には、初めてのデプロイの直後に 523 が出たら1分ほど待つと直ることがある、と書かれています。この記事ではデプロイせず、送る中身を確かめる --dry-run まで実行しました。
$ npx wrangler deploy --dry-run --outdir dist
Total Upload: 0.98 KiB / gzip: 0.51 KiB
Your Worker has access to the following bindings:
Binding Resource
env.MY_KV (local-dummy-id) KV Namespace
env.GREETING ("こんにちは") Environment Variable
--dry-run: exiting now.
$ npx wrangler whoami
Getting User settings...
You are not authenticated. Please run `wrangler login`.
dist には、まとめた index.js(1,000バイト)とソースマップができました。公開する方法は3つあります。
- 1まず試す → workers.devWorker ごとに自動で付くサブドメイン。公式は個人や趣味の用途向けと説明し、止めることもできる
- 2Worker が応答の元になる → カスタムドメインCloudflare のゾーンの中のドメイン・サブドメインを Worker に割り当てる。ゾーンあたり100まで
- 3元のサーバーの前に挟む → ルートURL のパターンを Worker に割り当てる。元のサーバーは Cloudflare の外でもよい。ゾーンあたり1,000まで
公式は、本番の Worker は workers.dev ではなくルートかカスタムドメインで動かすよう勧めています。どちらもドメインが Cloudflare のゾーンにあることが前提です。
- 1compatibility_date を入れる作り始めた日付を書く。日付ごとにランタイムの変更を選ぶ仕組みで、以前の日付もずっと使える、と公式にある
- 2--dry-run で中身と大きさを見るバインディングの一覧と Total Upload を確かめる。圧縮前の上限は64MiB
- 3シークレットを先に入れる手元の .dev.vars は本番に送られない。本番は secret put かダッシュボードで入れる
- 4Cron は UTC で書く日本時間から9時間引く。反映に最大15分かかる
- 5無料プランの上限を超えたときの動きを決めるルートを使うなら Fail open か Fail closed を選ぶ
ビルド・リリース・ロールバックの考え方は関連記事「デプロイとは|ビルド・リリースとの違いとロールバックを実例で解説」で扱っています。
Cloudflare WorkersとPagesの違い
この節では、同じ Cloudflare の Pages と Workers のどちらを使うかの考え方が分かります。
2026年11月18日時点で、Cloudflare Pages の公式ドキュメントの先頭には「Start new projects with Workers.」(新しいプロジェクトは Workers で始める)と書かれています。その前には、Workers は Pages の使い道のほとんどに対応し、より広い機能を持つ、という趣旨の文があります。Pages から Workers への移行ガイドの対応表を整理すると次のとおりです。
| 区分 | 機能(公式の対応表より) |
|---|---|
| 両方で使える | ロールバック、プレビューの URL、手元での開発、リダイレクト、静的アセットのヘッダー、D1・KV・R2 などのバインディング |
| Workers だけ | 段階的なデプロイ、Workers Logs、Logpush、Cron Triggers、Queues の受け手、Email Workers、--remote での開発 |
| Pages だけ | Cloudflare のゾーンの外にあるカスタムドメイン |
| Workers は一部対応 | Early Hints、ブランチごとのデプロイの制御、ファイルの配置によるルーティング、Pages のプラグイン |
Pages の使い方・デプロイの3つの方法・移行の注意はCloudflare Pagesとは|使い方・デプロイ3通りとWorkersとの関係にまとめています。AWS と Cloudflare の会社としての違いは関連記事「クラウドシェア1位はどこ?AWSとCloudflareの違い」で、AWS 側のサーバーレスである Lambda の書き方は関連記事「AWS Lambda Python入門|3.14対応handler例とローカルテスト」で扱っています。
この記事の Worker は if で URL を分けていますが、道筋が増えたら Web フレームワークを組み合わせる方法もあります。Hono の書き方は関連記事「Hono入門|Node.jsでルーティング・zod検証・JWT・RPC」で扱っています。
Cloudflare Workersのよくあるエラー・つまずき(原文つき)
この節では、手元で実際に出したエラーの原文と、本番で出るエラーの意味・直し方が分かります。
手元で出したエラーの原文です。わざと壊したコードや設定で再現しました。
# 1. 応答(Response)を return し忘れた
TypeError: Incorrect type for Promise: the Promise did not resolve to 'Response'.
# 2. 設定に書いていないバインディングを使った(env.MY_BUCKET が無い)
TypeError: Cannot read properties of undefined (reading 'get')
at Object.fetch (file:///.../src/index.js:27:39)
# 3. 同じポートで2つ目の wrangler dev を起動した
✘ [ERROR] Address already in use (127.0.0.1:8790). Please check that you are not
already running a server on this address or specify a different port with --port.
# 4. 設定ファイルに main が無い
✘ [ERROR] Missing entry-point to Worker script or to assets directory
# 5. wrangler.jsonc のカンマ抜け
✘ [ERROR] CommaExpected
wrangler.jsonc:1:32:
1 │ { "name": "bad", "main": "x.js" "compatibility_date": "2026-11-01" }
╵ ~~~~~~~~~~~~~~~~~~~~
コードの中で例外が起きたときは、手元ではブラウザ・curl の側にも 500 とスタックトレースが返りました(Error: わざと起こしたエラー と行番号)。これは手元の開発用の表示で、本番の挙動とは分けて考えます。
| 症状・原文 | 原因 | 直し方 |
|---|---|---|
| did not resolve to 'Response' | fetch ハンドラーが Response を返していない | すべての分かれ道で return new Response(...) を書く。最後に 404 を返す行を置く |
| Cannot read properties of undefined | env の名前と設定ファイルの binding が合っていない | binding の綴りを合わせる。wrangler types で型を作ると気づきやすい |
| Address already in use | 同じポートで別のサーバーが動いている | --port で変えるか、動いている側を止める。ss -ltnp で確かめる |
| Missing entry-point | main(入口のファイル)も assets も無い | wrangler.jsonc に "main": "src/index.js" を書く |
| CommaExpected | 設定ファイルの書き間違い | 示された行と列を直す。$schema を入れるとエディターが補ってくれる |
| Unable to fetch the Request.cf object | 外に出られず request.cf の見本を取れない | 手元の開発は代わりの値で続く。国などの値に頼る処理は本番で確かめる |
| Error 1027 | 無料プランの1日10万を超えた | UTC 0時に戻るのを待つか、有料プランにする。ルートの Fail open・closed を見直す |
| Error 1102 | CPU 時間かメモリの上限を超えた | 重い計算を減らす・分ける。有料プランは CPU の上限を延ばせる |
| 初めてのデプロイの直後に 523 | 公開の準備が終わっていない | 公式の案内では1分ほど待つ |
| 413 | リクエストボディがドメインのプランの上限を超えた | ボディを小さくするか分けて送る。上限はドメインのプランの表で確かめる |
判断表:Cloudflare Workersが合う場面・合わない場面
この節では、作りたいものに対して Workers を選ぶかどうかの目安が分かります。
| 作りたいもの・条件 | Workers の向き | 理由(公式の上限・仕様から) |
|---|---|---|
| 小さな API・Webhook の受け口 | 合う | 待ち時間は CPU 時間に数えない。無料で1日10万 |
| 静的なサイト+少しのサーバー処理 | 合う | 静的アセットは無料・無制限 |
| 既存のサーバーの前でヘッダーや振り分けを変える | 合う | ルートで URL の一部だけに割り当てられる |
| 決まった時刻のバッチ | 条件つきで合う | Cron は UTC。有料なら1回最大15分 |
| CPU を長く使う変換・計算 | 合いにくい | 無料は10ミリ秒、有料でも最大5分。CPU 時間が料金になる |
| メモリを多く使う処理 | 合いにくい | 1つの Worker で128MB |
| ドメインを Cloudflare に置けない | 確かめが要る | カスタムドメイン・ルートはゾーンが前提。workers.dev は趣味向け |
| Java・C# で書きたい | 確かめが要る | 公式の第一級の言語は JS・TS・Python・Rust |
Cloudflare Workersのよくある質問
この節では、Cloudflare Workers についてよく調べられる疑問への答えが分かります。
Q. Cloudflare Workers は無料で使えますか?
使えます。Workers Free は1日10万リクエスト、1回あたり CPU 時間10ミリ秒までです(2026年11月18日時点の公式の記載)。上限は UTC の0時に戻ります。
Q. 有料プランはいくらからですか?
アカウントあたり月5ドルからです。月1,000万リクエストと CPU 時間3,000万ミリ秒を含み、超えた分は100万リクエストあたり0.30ドル、100万 CPU ミリ秒あたり0.02ドルです。
Q. ログインしなくても試せますか?wrangler dev によるローカル実行、wrangler types、wrangler deploy --dry-run、wrangler d1 execute --local は、この記事の確認ではログインなしで動きました。デプロイ・--remote・本物の資源につなぐ操作にはログインが要ります。
Q. wrangler.toml と wrangler.jsonc のどちらを使えばよいですか?
どちらも使えます。公式の始め方で作られるのは wrangler.jsonc で、公式の例も両方の書き方で載っています。$schema を書くとエディターの補完が効きます。
Q. 手元の KV や D1 のデータはどこにありますか?
この記事の確認では、プロジェクトの中の .wrangler/state/v3/ の下にありました。起動し直しても残り、本物の資源とは別物です。
Q. Python で書けますか?
書けます。2026年9月21日の公式ブログで Python Workers の一般提供が発表されています。この記事では Python Workers は動かしていません。
Q. Cron の時刻が9時間ずれます。
Cron Triggers は UTC で動きます。日本時間から9時間引いた時刻で書きます。手元の workerd も TZ=UTC で動く、と公式にあります。
Q. Workers と Pages のどちらで始めるべきですか?
Pages の公式ドキュメントは、新しいプロジェクトを Workers で始めるよう案内しています。ドメインを Cloudflare のゾーンに置けない場合のカスタムドメインは、対応表では Pages だけの項目です。
Q. 環境変数を変えたのに手元で反映されません。.dev.vars があると .env は読まれません。どちらか一方にそろえ、起動し直します。vars は環境の間で引き継がれないので、--env を使うときは環境ごとに書きます。
Q. 手元の wrangler dev を他の人に見せてよいですか?
公式は、Miniflare は堅牢な隔離の仕組みではなく、信頼できないコードは VM など安全な環境で動かすよう書いています。手元の開発用サーバーは 127.0.0.1 のまま使い、共有には正式な公開の方法を選びます。
まとめ
この節では、Cloudflare Workers の要点を5つにまとめます。
- Cloudflare Workers は、Cloudflare のネットワーク上でコードを動かすサーバーレスの実行環境で、本番と同じ
workerdを手元でも動かせる - 無料は1日10万リクエスト・1回 CPU 10ミリ秒、有料は月5ドルから。公式の価格例5つは Python の式で同じ合計になった
- Wrangler はプロジェクトごとに入れ、
wrangler devでログインせずに手元で動かせる。KV・D1 も手元でシミュレーションされ、データは.wrangler/stateに残る - 秘密の値は
varsに書かず、本番はsecret put、手元は.dev.vars(Git に入れない)。Cron は UTC - 新しいプロジェクトは Workers で始めるよう公式が案内している。公開はルートかカスタムドメインが本番向け
参考・出典
この節では、記事で確かめた公式の資料が分かります(確認日 2026年11月18日)。
- Cloudflare Docs「Cloudflare Workers」:https://developers.cloudflare.com/workers/
- Cloudflare Docs「Pricing」(Workers):https://developers.cloudflare.com/workers/platform/pricing/
- Cloudflare Docs「Limits」(Workers):https://developers.cloudflare.com/workers/platform/limits/
- Cloudflare Docs「Install/Update Wrangler」:https://developers.cloudflare.com/workers/wrangler/install-and-update/
- Cloudflare Docs「Get started - CLI」:https://developers.cloudflare.com/workers/get-started/guide/
- Cloudflare Docs「Development & testing」:https://developers.cloudflare.com/workers/development-testing/
- Cloudflare Docs「Environment variables」:https://developers.cloudflare.com/workers/configuration/environment-variables/
- Cloudflare Docs「Secrets」:https://developers.cloudflare.com/workers/configuration/secrets/
- Cloudflare Docs「Cron Triggers」:https://developers.cloudflare.com/workers/configuration/cron-triggers/
- Cloudflare Docs「Compatibility dates」:https://developers.cloudflare.com/workers/configuration/compatibility-dates/
- Cloudflare Docs「Routes and domains」:https://developers.cloudflare.com/workers/configuration/routing/
- Cloudflare Docs「Choosing a data or storage product」:https://developers.cloudflare.com/workers/platform/storage-options/
- Cloudflare Docs「Languages」:https://developers.cloudflare.com/workers/languages/
- Cloudflare Docs「Migrate from Pages to Workers」:https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/
- Cloudflare Docs「Cloudflare Pages」:https://developers.cloudflare.com/pages/
- The Cloudflare Blog「Python Workers are now generally available」:https://blog.cloudflare.com/python-workers-ga/
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Cloudflare Workersとは|使い方・料金・無料枠を手元で実演」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。