Cloudflare Workers ローカル開発環境基本フロー

1. 全体の流れ

Windows
  ↓
Node.js
  ↓
npm
  ↓
プロジェクト作成
  ↓
Wrangler
  ↓
.gitignore
  ↓
Workers用ファイル作成
  ↓
ローカル開発
  ↓
GitHub
  ↓
Cloudflare

Node.jsをインストール
Node.js / npmを確認
プロジェクトフォルダを作成
package.json を作成
Wranglerをインストール
.gitignore を作成
wrangler.jsonc を作成
src/index.js を作成
必要に応じて public/ を作成
npx wrangler dev でローカル確認
GitHubへpush
Cloudflareへデプロイ

2. Node.jsを準備する

まずWindowsへNode.jsをインストールします。インストール後、PowerShellで確認します。

node -v
npm -v

両方ともバージョン番号が表示されればOKです。

Node.js
  │
  └─ npm

Node.jsは、Cloudflare Workersそのものを本番環境で動かすためのものではありません。主にローカルPCで npm、Wrangler、その他の開発ツールを動かすための土台として使用します。

3. プロジェクトフォルダを作成する

例えば以下のようなフォルダを作ります。

D:\coding\cloudflare\my-worker

PowerShellで移動します。

cd D:\coding\cloudflare\my-worker

4. npmプロジェクトを初期化する

プロジェクトフォルダ内で実行します。

npm init -y

package.json は、このプロジェクトでどのNode.jsパッケージを使用するかを管理するファイルです。

5. Wranglerをインストールする

Cloudflare Workersを操作するCLIが Wrangler です。プロジェクト内へインストールします。

npm install -D wrangler@latest

インストール後、確認します。

npx wrangler --version

6. npmとnpxの違い

npm
↓
パッケージをインストール・管理する

npx
↓
インストールしたパッケージを実行する

npm install -D wrangler@latest はWranglerをインストールする処理です。一方、npx wrangler dev はインストールしたWranglerを実行する処理です。

7. `.gitignore` を作成する

GitHubへ送らないファイルを指定するために、.gitignore をプロジェクト直下に作成します。

# Node.js
node_modules/

# Cloudflare / Wrangler
.wrangler/

# Environment / Secrets
.dev.vars
.dev.vars.*
.env
.env.*

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# OS files
Thumbs.db
.DS_Store

# Editor
.vscode/
.idea/

8. GitHubへ送るもの・送らないもの

GitHubへ送る

.gitignore
package.json
package-lock.json
wrangler.jsonc
src/
public/

GitHubへ送らない

node_modules/
.wrangler/
.dev.vars
.env
*.log

ソースコード、Cloudflare設定、パッケージ情報は送ります。再生成できるもの、PC固有のもの、Secretは送りません。

9. Workers用のフォルダを作成する

my-worker/
│
├─ node_modules/
├─ public/
│   ├─ index.html
│   ├─ css/
│   └─ js/
│
├─ src/
│   └─ index.js
│
├─ .gitignore
├─ package.json
├─ package-lock.json
└─ wrangler.jsonc

10. 各ファイルの役割

`package.json`

Node.js/npm側の設定です。Wranglerをインストールすると、devDependenciesに記録されます。

{
  "devDependencies": {
    "wrangler": "^4.x.x"
  }
}

`package-lock.json`

実際にインストールされた依存パッケージのバージョンを固定します。これはGitHubへpushします。

`wrangler.jsonc`

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-08-15",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

`src/index.js`

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

    if (url.pathname === "/api/test") {
      return Response.json({
        success: true,
        message: "Worker is running"
      });
    }

    return env.ASSETS.fetch(request);
  }
};

`public/`

HTML・CSS・JavaScript・画像など、ブラウザへ配信する静的ファイルを置きます。

11. ローカル環境でWorkerを起動する

プロジェクト直下で実行します。

npx wrangler dev

通常は http://localhost:8787 でアクセスできます。

VS Code
  ↓
コードを書く
  ↓
Wrangler
  ↓
ローカルWorkers環境
  ↓
http://localhost:8787

12. Workerと静的ファイルの関係

ブラウザ
   ↓
http://localhost:8787
   ↓
src/index.js
   │
   ├─ /api/test
   │      ↓
   │   Workerが処理
   │
   └─ その他
          ↓
       public/
          ↓
       index.html

src/index.js はサーバー側の処理、public/ はブラウザへ配信するHTML/CSS/JSという役割分担です。

13. Cloudflareへログインする

npx wrangler login

ブラウザが開くのでCloudflareへのアクセスを許可します。ログイン状態は次のコマンドで確認できます。

npx wrangler whoami

14. Cloudflareへ直接デプロイする場合

npx wrangler deploy

ローカルPC
    ↓
Wrangler
    ↓
Cloudflare
    ↓
Worker

15. GitHubを使ってデプロイする場合

ローカル
↓
Git
↓
GitHub
↓
Cloudflare
↓
自動デプロイ

git add .
git commit -m "update"
git push

16. `node_modules` をGitHubへ送らなくても動く理由

ローカルには node_modules/ がありますが、GitHubには送りません。代わりに package.json と package-lock.json をGitHubへ送ります。

GitHub
↓
package.json
package-lock.json
↓
必要なnpmパッケージをインストール
↓
node_modulesをCloudflare側で作成
↓
Wranglerを実行

17. ローカルから本番公開までの全体像

【Windows PC】

Node.js
  ↓
npm
  ↓
Wrangler
  ↓

Workersプロジェクト
│
├─ src/index.js
├─ public/
├─ wrangler.jsonc
├─ package.json
├─ package-lock.json
└─ .gitignore
  ↓

npx wrangler dev
  ↓

http://localhost:8787
  ↓

ローカル動作確認
  ↓

Git
  ↓
GitHub
  ↓
Cloudflare
  ↓

Workers本番環境

18. 最低限覚えておくコマンド

# Node.js確認
node -v

# npm確認
npm -v

# Node.jsプロジェクト初期化
npm init -y

# Wranglerインストール
npm install -D wrangler@latest

# Wrangler確認
npx wrangler --version

# Cloudflareログイン
npx wrangler login

# ログイン状態確認
npx wrangler whoami

# ローカルWorkers起動
npx wrangler dev

# Cloudflareへ直接デプロイ
npx wrangler deploy

19. 環境構築チェックリスト

Node.jsをインストールした
node -v が実行できる
npm -v が実行できる
プロジェクトフォルダを作成した
npm init -y を実行した
package.json が作成された
Wranglerをインストールした
npx wrangler --version が実行できる
.gitignore を作成した
node_modules/ をGit管理から除外した
.env / .dev.vars をGit管理から除外した
wrangler.jsonc を作成した
src/index.js を作成した
必要なら public/ を作成した
npx wrangler dev でローカル確認できた
GitHubへpushできる
Cloudflareへデプロイできる

20. 最短で覚える

Node.js
↓
npm init -y
↓
npm install -D wrangler@latest
↓
.gitignore
↓
wrangler.jsonc
↓
src/index.js
↓
public/
↓
npx wrangler dev
↓
GitHub
↓
Cloudflare

特に重要なのは、Node.js、npm、Wrangler、wrangler.jsonc、src/index.js、public/、.gitignore の役割分担です。

Cloudflare Workers ローカル開発環境 基本フロー