Cloudflare Workers は、Cloudflare のエッジネットワーク上で動く JavaScript/TypeScript 実行環境です。世界200か所以上のデータセンターにコードが配置されるため、ユーザーに近い場所でリクエストを処理できます。料金プランは無料枠（1日10万リクエスト）から始まり、サーバーレスでスケールするのでVPSを常時起動する必要がありません。
Ubuntu で開発する場合、公式の CLI ツール「wrangler」を使います。wrangler dev コマンドでローカルに開発サーバーが立ち上がり、wrangler deploy で本番環境にデプロイできます。本記事では Ubuntu 24.04 LTS に Node.js と wrangler をインストールし、実際に Worker を作って動かすまでの手順を実測結果とともに解説します。
この記事のポイント
- Ubuntu 24.04 標準の
aptで入る Node.js は 18.19.1 と古い。NodeSource 公式リポジトリを使い Node.js 22 LTS を入れること npm install -g wranglerで wrangler をインストール。wrangler --versionで 4.x が返れば準備完了wrangler init→wrangler devでローカルのlocalhost:8787にエッジ相当の実行環境が立ち上がる- ローカルで動いたら
wrangler deploy1コマンドで Cloudflare 本番にデプロイできる
動作確認済みの環境
本記事のコマンドは以下の環境で実行しています。
| 項目 | バージョン / 詳細 |
|---|---|
| OS | Ubuntu 24.04 LTS（Docker公式イメージ：ubuntu:24.04） |
| Node.js | v22.23.0（NodeSource node_22.x リポジトリ） |
| npm | 10.9.8 |
| wrangler（Docker環境） | 4.103.0（NodeSource + Node.js 22 環境での最新版） |
| wrangler（応答速度計測環境） | 4.86.0（Node.js 20.18.1） |
| 確認日 | 2026-06-21 |
Node.js のインストール
手順1：Ubuntu 標準 apt では古いバージョンが入る
まず実態を確認します。apt-cache policy nodejs を実行すると、Ubuntu 24.04 のデフォルトリポジトリ（universe）には Node.js 18.19.1 しか入っていないことが分かります。
nodejs:
Installed: (none)
Candidate: 18.19.1+dfsg-6ubuntu5
Version table:
18.19.1+dfsg-6ubuntu5 500
500 http://archive.ubuntu.com/ubuntu noble/universe amd64 Packages
Node.js 18 は wrangler の最低要件はギリギリ満たしますが、最新の wrangler（4.x）は Node.js 20 以上を推奨しています。NodeSource の公式リポジトリを使って Node.js 22 LTS を入れるのが現在の標準的な方法です。
手順2：NodeSource リポジトリを追加して Node.js 22 をインストール
curl でセットアップスクリプトを落として実行するだけです。Docker コンテナ（ubuntu:24.04）で実際に実行したインストールログを示します。
$ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
## Executing NodeSource setup script v1.1.0 for Node.js LTS (v22.x) …
## Repository configured successfully.
## To install Node.js, run: apt install nodejs -y
$ sudo apt-get install -y nodejs
Selecting previously unselected package nodejs.
Unpacking nodejs (22.23.0-1nodesource1) …
Setting up nodejs (22.23.0-1nodesource1) …
$ node –version
v22.23.0
$ npm –version
10.9.8
インストール後の実測値は Node.js v22.23.0、npm 10.9.8 でした。
注意
curl ... | sudo bash はセキュリティ上の懸念があります。気になる場合は一度スクリプトの内容を curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesource_setup.sh で保存して確認してから実行してください。NodeSource は Cloudflare Workers の公式ドキュメントでも推奨されているリポジトリです。
wrangler CLI のインストール
Node.js が入ったら npm で wrangler をグローバルインストールします。
added 35 packages in 9s
$ wrangler –version
4.103.0
Docker コンテナ内での実測では 35 パッケージ、9秒でインストール完了しました。wrangler --version で 4.103.0 が返れば成功です。
wrangler のコマンド体系は以下のように整理されています。
Cloudflare アカウントへのログイン
Worker をデプロイするには Cloudflare のアカウントが必要です（無料で作れます）。ログインコマンドを実行するとブラウザが開き、認証後に自動でトークンが保存されます。
Attempting to open a link in your default browser…
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth…
Successfully logged in.
$ wrangler whoami
Getting User settings…
👋 You are logged in with an OAuth Token, associated with the email: you@example.com!
WSL / サーバー環境の場合
WSL や SSH 接続先のサーバーではブラウザが開きません。その場合は wrangler login --no-browser を実行すると認証 URL が表示されるので、ローカルのブラウザでそのURLを開いて認証してください。
プロジェクトの作成（wrangler init）
手順3：wrangler init でプロジェクトを初期化する
wrangler init を実行すると、対話式でテンプレートを選べます。-y フラグを付けるとデフォルト設定で一括作成します。実際に wrangler init my-first-worker --yes を実行して生成されたプロジェクト構成を確認しました。
⛅️ wrangler 4.103.0
───────────────────
🌀 Running `npm create cloudflare my-first-worker -y — –wrangler-defaults`…
👋 Welcome to create-cloudflare v2.67.4!
├ In which directory do you want to create your application?
│ dir ./my-first-worker
├ What would you like to start with?
│ category Hello World example
├ Which language do you want to use?
│ lang TypeScript
✅ Application created successfully!
$ cd my-first-worker && ls
package.json public/ src/ test/ tsconfig.json wrangler.jsonc
生成されたファイルの役割は次の通りです。
メインのコードは src/index.ts に入っています。
export default {
async fetch(request, env, ctx): Promise<Response> {
const url = new URL(request.url);
switch (url.pathname) {
case ‘/message’:
return new Response(‘Hello, World!’);
case ‘/random’:
return new Response(crypto.randomUUID());
default:
return new Response(‘Not Found’, { status: 404 });
}
},
} satisfies ExportedHandler<Env>;
fetch ハンドラが Worker の核で、request.url を見てパスごとに Response を返す構造です。crypto.randomUUID() は Workers ランタイムが提供する API で、Node.js の crypto モジュールとは別物です。
ローカル開発サーバーの起動（wrangler dev）
手順4：wrangler dev でローカルサーバーを起動する
プロジェクトディレクトリで npm run dev（または wrangler dev）を実行すると、localhost:8787 にエッジランタイム相当の開発サーバーが立ち上がります。
⛅️ wrangler 4.103.0
──────────────────────────────────────────────
⎔ Starting local server…
[wrangler:info] Ready on http://localhost:8787
別のターミナルで curl を叩いて動作を確認します。
Hello, World!
$ curl http://localhost:8787/random
2d231cc5-692f-4456-981f-648621f159bd
$ curl -o /dev/null -w “%{time_total}s\n” http://localhost:8787/message
0.002179s
/message への応答は実測で平均 2.2ms（5回計測：最小 1.3ms〜最大 4.4ms）でした。この計測は wrangler 4.86.0 / Node.js 20.18.1 環境で実施しています。初回リクエストは JIT コンパイルで 4ms 前後かかりますが、2回目以降は 1〜2ms に落ち着きます。
ブラウザで http://localhost:8787/ を開くと、public/index.html に書かれた静的ページが表示されます。
/message エンドポイントへのブラウザアクセスはこのように返ります。
wrangler dev は src/index.ts を変更するとホットリロードがかかります。ファイルを保存するだけでブラウザ側も即座に反映されるので、開発中のストレスがほぼありません。
コードを変更してみる
手順5：Worker のレスポンスを書き換える
src/index.ts を開いて、新しいパスを追加してみます。
case ‘/hello’:
return new Response(‘こんにちは from エッジ!’);
$ curl http://localhost:8787/hello
こんにちは from エッジ!
Worker は HTTP リクエストをそのままインターセプトできるので、プロキシ・A/Bテスト・リダイレクト・認証ゲートウェイなど、通常のサーバーサイドアプリと同じことが CDN の手前で実行できます。
本番環境へのデプロイ（wrangler deploy）
手順6：Cloudflare へデプロイする
wrangler login で認証済みなら、npm run deploy 1コマンドで本番環境に反映できます。
⛅️ wrangler 4.x
──────────────────────────────────────────────
Total Upload: X.XX KiB / gzip: X.XX KiB
Deployed my-first-worker triggers (X.XX sec)
https://my-first-worker.your-subdomain.workers.dev
注意（デプロイ出力について）
上記のターミナルは wrangler deploy の出力形式を示す概念図です（X.XX の部分は実際のコードサイズにより変わります）。本記事のローカル検証環境では Cloudflare 認証が不要な wrangler dev の範囲まで実測しており、デプロイ自体は実行していません。
デプロイが完了すると *.workers.dev のサブドメインで即座にグローバルにアクセスできます。デプロイの速さは Cloudflare のエッジネットワークの大きなメリットです。
無料プランの制限
- 1日 10万リクエストまで無料（超過分は $0.30/100万リクエスト）
- CPU 時間：1リクエストあたり 10ms（無料）
- Workers の数：最大 100（無料）
- カスタムドメインは独自ドメインの Cloudflare 管理が必要
wrangler.jsonc の主な設定項目
wrangler init で生成される wrangler.jsonc の重要な設定を確認します。
{
“name”: “my-first-worker”,
“main”: “src/index.ts”,
“compatibility_date”: “2025-11-01”,
“assets”: {
“directory”: “./public”
},
“observability”: {
“enabled”: true
}
}
compatibility_date は重要な設定で、Workers ランタイムの動作基準日を指定します。古い日付を設定するとその日以降のランタイム変更が適用されず、動作の一貫性を保てます。ただし wrangler init が生成するデフォルトの wrangler.jsonc には <COMPATIBILITY_DATE> というプレースホルダーが入るため、上記例のように実際の日付に書き換える必要があります。
よくあるエラーと解決策
①「compatibility_date field should be a valid ISO-8601 date」エラー
– “compatibility_date” field should be a valid ISO-8601 date (YYYY-MM-DD),
but got “<COMPATIBILITY_DATE>”.
wrangler.jsonc にプレースホルダーが残っている状態です。<COMPATIBILITY_DATE> を "2025-11-01" のような実際の日付に書き換えてください。<WORKER_NAME> も同様に英数字の名前に変更が必要です。
②「Address already in use; port 8787」エラー
::bind(sockfd, &addr.generic, addrlen): Address already in use
別のターミナルで wrangler dev がすでに起動しています。pkill -f workerd で既存のプロセスを落としてから再起動してください。ポートを変えたい場合は wrangler dev --port 9000 のように指定できます。
③「Workers runtime binary is too old」エラー
インストールした wrangler が古く、compatibility_date で指定した日付をサポートしていない場合です。
added 35 packages, changed 1 package
$ wrangler –version
4.103.0
npm update -g wrangler で最新版に更新すれば解決します。
まとめ
Ubuntu 24.04 で Cloudflare Workers の開発環境を構築する手順は以下の4ステップです。
- NodeSource 公式リポジトリで Node.js 22 LTS（v22.23.0）をインストール。Ubuntu 標準の 18系は避ける
npm install -g wranglerで wrangler をインストール（実測 9秒・35パッケージ）wrangler initでプロジェクトを作成。src/index.tsにフェッチハンドラを書くwrangler devでローカル確認、wrangler deployで Cloudflare 本番へ
ローカルの wrangler dev サーバーは応答が平均 2.2ms と速く、開発サイクルが快適でした。Worker のコードはグローバル 200拠点のエッジで動くため、オリジンサーバー（VPS等）の前段に挟むアーキテクチャと相性がよいです。VPS でバックエンド API を動かしつつ、Cloudflare Workers でキャッシュ・認証・ルーティングを担うという構成も選択肢に入ります。
本格的なサーバーサイドのバックエンドを動かすなら VPS も引き続き有力です。
コメント