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 crypto	使用 crypto.getRandomValues
Cannot find module	全部	缺少 polyfill	检查 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. 更新环境变量访问方式：使用 env 参数，而不是 process.env
4. 替换文件系统：使用 R2/KV 存储
5. 处理异步任务：使用 ctx.waitUntil() 执行后台任务
6. 本地测试：使用 wrangler dev 验证
7. 性能测试：确保不超过 CPU 限制

另请参阅

• workers-runtime-apis - Workers 中可用的 API
• workers-performance - 优化技巧
• cloudflare-worker-base - Workers 基本设置