cloudflare-workers-migration

Workers 移行ガイド

さまざまなプラットフォームから Cloudflare Workers に既存のアプリケーションを移行します。

移行判断ツリー

What are you migrating from?
├── AWS Lambda
│   └── Node.js handler? → Lambda adapter pattern
│   └── Python? → Consider Python Workers
│   └── Container/custom runtime? → May need rewrite
├── Vercel/Next.js
│   └── API routes? → Minimal changes with adapter
│   └── Full Next.js app? → Use OpenNext adapter
│   └── Middleware? → Direct Workers equivalent
├── Express/Node.js
│   └── Simple API? → Hono (similar API)
│   └── Complex middleware? → Gradual migration
│   └── Heavy node: usage? → Compatibility layer
└── Other Edge (Deno Deploy, Fastly)
    └── Standard Web APIs? → Minimal changes
    └── Platform-specific? → Targeted rewrites

プラットフォームの比較

機能	Workers	Lambda	Vercel	Express
コールドスタート	~0ms	100-500ms	10-100ms	該当なし
CPU 制限	50ms/10ms	15 min	10s	なし
メモリ	128MB	10GB	1GB	システム
最大レスポンス	6MB（ストリーミングは無制限）	6MB	4.5MB	なし
グローバルエッジ	300+ PoPs	リージョン	~20 PoPs	手動
Node.js API	一部	すべて	すべて	すべて

移行時によくあるエラー 10 件

エラー	移行元	原因	解決策
fs is not defined	Lambda/Express	ファイルシステムへのアクセス	ストレージには KV/R2 を使用します
Buffer is not defined	Node.js	Node.js のグローバル	node:buffer からインポートします
process.env undefined	すべて	環境変数へのアクセス方法	env パラメーターを使用します
setTimeout not returning	Lambda	非同期処理のパターン	ctx.waitUntil() を使用します
require() not found	Express	CommonJS	ESM インポートに変換します
Exceeded CPU time	すべて	長時間の計算	処理を分割するか、DO を使用します
body already consumed	Express	リクエストボディ	読み取る前にクローンします
Headers not iterable	Lambda	Headers API	Headers コンストラクターを使用します
crypto.randomBytes	Node.js	Node.js の crypto	crypto.getRandomValues を使用します
Cannot find module	すべて	ポリフィルの不足	Workers との互換性を確認します

移行の簡単なパターン

AWS Lambda ハンドラー

// Before: AWS Lambda
export const handler = async (event, context) => {
  const body = JSON.parse(event.body);
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello' }),
  };
};

// After: Cloudflare Workers
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.json();
    return Response.json({ message: 'Hello' });
  },
};

Express ミドルウェア

// Before: Express
app.use((req, res, next) => {
  if (!req.headers.authorization) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

// After: Hono Middleware
app.use('*', async (c, next) => {
  if (!c.req.header('Authorization')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
  await next();
});

環境変数

// Before: Node.js
const apiKey = process.env.API_KEY;

// After: Workers
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const apiKey = env.API_KEY;
    // ...
  },
};

Node.js の互換性

Workers は互換性フラグを使用して多くの Node.js API をサポートします。

// wrangler.jsonc
{
  "compatibility_flags": ["nodejs_compat_v2"],
  "compatibility_date": "2024-12-01"
}

nodejs_compat_v2 でサポートされるもの：

• crypto（ほとんどのメソッド）
• buffer（Buffer クラス）
• util（promisify、types）
• stream（Readable、Writable）
• events（EventEmitter）
• path（すべてのメソッド）
• string_decoder
• assert

サポートされないもの（代替手段が必要）：

• fs → R2/KV を使用します
• child_process → 使用できません
• cluster → 該当しません
• dgram → サポートされません
• net → fetch/WebSocket を使用します
• tls → プラットフォームが処理します

リファレンスを読み込むタイミング

リファレンス	読み込むタイミング
references/lambda-migration.md	AWS Lambda 関数を移行する場合
references/vercel-migration.md	Vercel/Next.js から移行する場合
references/express-migration.md	Express/Node.js アプリを移行する場合
references/node-compatibility.md	Node.js API の互換性に問題がある場合

移行チェックリスト

1. 依存関係を分析する：サポートされていない Node.js API がないか確認します
2. ESM に変換する：require() を import に置き換えます
3. 環境変数へのアクセスを更新する：process.env の代わりに env パラメーターを使用します
4. ファイルシステムを置き換える：ストレージには R2/KV を使用します
5. 非同期処理に対応する：バックグラウンドタスクには ctx.waitUntil() を使用します
6. ローカルでテストする：wrangler dev で動作を確認します
7. パフォーマンステストを行う：CPU 制限を超えないことを確認します

関連項目

• workers-runtime-apis - Workers で利用可能な API
• workers-performance - 最適化の手法
• cloudflare-worker-base - Workers の基本設定