name: workers-migration description: 从 AWS Lambda、Vercel、Express 和 Node.js 迁移到 Cloudflare Workers。适用于将现有应用程序移植到边缘、适配无服务器函数或解决 Node.js API 兼容性问题。 version: 1.0.0

Workers 迁移指南

将现有应用程序从各种平台迁移到 Cloudflare Workers。

迁移决策树

您从什么平台迁移？
├── AWS Lambda
│   └── Node.js 处理程序？ → Lambda 适配器模式
│   └── Python？ → 考虑 Python Workers
│   └── 容器/自定义运行时？ → 可能需要重写
├── Vercel/Next.js
│   └── API 路由？ → 使用适配器进行最小更改
│   └── 完整的 Next.js 应用？ → 使用 OpenNext 适配器
│   └── 中间件？ → 直接使用 Workers 等效功能
├── Express/Node.js
│   └── 简单 API？ → Hono（类似 API）
│   └── 复杂中间件？ → 逐步迁移
│   └── 重度使用 node：？ → 兼容性层
└── 其他边缘平台（Deno Deploy、Fastly）
    └── 标准 Web API？ → 最小更改
    └── 平台特定功能？ → 针对性重写

平台比较

特性	Workers	Lambda	Vercel	Express
冷启动	~0毫秒	100-500毫秒	10-100毫秒	不适用
CPU 限制	50毫秒/10毫秒	15分钟	10秒	无限制
内存	128MB	10GB	1GB	系统内存
最大响应	6MB（流式传输无限制）	6MB	4.5MB	无限制
全球边缘节点	300+ 个接入点	区域部署	~20 个接入点	手动部署
Node.js API 支持	部分	完整	完整	完整

前十迁移错误

错误	来源	原因	解决方案
`fs 未定义`	Lambda/Express	文件系统访问	使用 KV/R2 进行存储
`Buffer 未定义`	Node.js	Node.js 全局对象	从 `node:buffer` 导入
`process.env 未定义`	所有	环境变量访问模式	使用 `env` 参数
`setTimeout 不返回`	Lambda	异步模式	使用 `ctx.waitUntil()`
`require() 未找到`	Express	CommonJS	转换为 ESM 导入
`超出 CPU 时间`	所有	长计算	分块处理或使用 DO
`body 已使用`	Express	请求体	在读取前克隆
`Headers 不可迭代`	Lambda	Headers API	使用 Headers 构造函数
`crypto.randomBytes`	Node.js	Node crypto	使用 `crypto.getRandomValues`
`找不到模块`	所有	缺少 polyfill	检查 Workers 兼容性

快速迁移模式

AWS Lambda 处理程序

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

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

Express 中间件

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

// 之后：Hono 中间件
app.use('*', async (c, next) => {
  if (!c.req.header('Authorization')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
  await next();
});

环境变量

// 之前：Node.js
const apiKey = process.env.API_KEY;

// 之后：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、类型）
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 兼容性问题时

迁移清单

分析依赖：检查不支持的 Node.js API
转换为 ESM：用 import 替换 require()
更新环境变量访问：使用 env 参数而非 process.env
替换文件系统：使用 R2/KV 进行存储
处理异步：使用 ctx.waitUntil() 进行后台任务
本地测试：使用 wrangler dev 验证
性能测试：确保不超过 CPU 限制

另请参阅

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