Back to Details

workers-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workers Migration Guide

Workers迁移指南

Migrate existing applications to Cloudflare Workers from various platforms.
将现有应用从多种平台迁移至Cloudflare Workers。

Migration Decision Tree

迁移决策树

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
你要从哪个平台迁移？
├── 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？→ 只需少量修改
    └── 平台特定API？→ 针对性重写

Platform Comparison

平台对比

FeatureWorkersLambdaVercelExpress
Cold Start~0ms100-500ms10-100msN/A
CPU Limit50ms/10ms15 min10sNone
Memory128MB10GB1GBSystem
Max Response6MB (stream unlimited)6MB4.5MBNone
Global Edge300+ PoPsRegional~20 PoPsManual
Node.js APIsPartialFullFullFull
特性WorkersLambdaVercelExpress
冷启动~0ms100-500ms10-100ms不适用
CPU限制50ms/10ms15分钟10秒无
内存128MB10GB1GB系统分配
最大响应大小6MB（流式传输无限制）6MB4.5MB无
全球边缘节点300+ PoPs区域节点~20 PoPs手动配置
Node.js APIs部分支持完全支持完全支持完全支持

Top 10 Migration Errors

十大常见迁移错误

ErrorFromCauseSolution
fs is not defined
Lambda/ExpressFile system accessUse KV/R2 for storage
Buffer is not defined
Node.jsNode.js globalsImport from 
node:buffer
process.env undefined
AllEnv access patternUse 
env
parameter
setTimeout not returning
LambdaAsync patternsUse 
ctx.waitUntil()
require() not found
ExpressCommonJSConvert to ESM imports
Exceeded CPU time
AllLong computationChunk or use DO
body already consumed
ExpressRequest bodyClone before read
Headers not iterable
LambdaHeaders APIUse Headers constructor
crypto.randomBytes
Node.jsNode cryptoUse 
crypto.getRandomValues
Cannot find module
AllMissing polyfillCheck Workers compatibility
错误来源平台原因解决方案
fs is not defined
Lambda/Express文件系统访问使用KV/R2进行存储
Buffer is not defined
Node.jsNode.js全局变量从
node:buffer
导入
process.env undefined
所有平台环境变量访问方式使用
env
参数
setTimeout not returning
Lambda异步模式问题使用
ctx.waitUntil()
require() not found
ExpressCommonJS语法转换为ESM导入
Exceeded CPU time
所有平台计算任务过长拆分任务或使用DO
body already consumed
Express请求体读取问题读取前先克隆请求
Headers not iterable
LambdaHeaders API差异使用Headers构造函数
crypto.randomBytes
Node.jsNode加密模块使用
crypto.getRandomValues
Cannot find module
所有平台缺少polyfill检查Workers兼容性

Quick Migration Patterns

快速迁移模式

AWS Lambda Handler

AWS Lambda处理器

typescript
// 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' });
  },
};
typescript
// 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 Middleware

Express中间件

typescript
// 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();
});
typescript
// 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();
});

Environment Variables

环境变量

typescript
// 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;
    // ...
  },
};
typescript
// 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 Compatibility

Node.js兼容性

Workers support many Node.js APIs via compatibility flags:
jsonc
// wrangler.jsonc
{
  "compatibility_flags": ["nodejs_compat_v2"],
  "compatibility_date": "2024-12-01"
}
Supported with nodejs_compat_v2:
  • crypto
    (most methods)
  • buffer
    (Buffer class)
  • util
    (promisify, types)
  • stream
    (Readable, Writable)
  • events
    (EventEmitter)
  • path
    (all methods)
  • string_decoder
  • assert
Not Supported (need alternatives):
  • fs
    → Use R2/KV
  • child_process
    → Not possible
  • cluster
    → Not applicable
  • dgram
    → Not supported
  • net
    → Use fetch/WebSocket
  • tls
    → Handled by platform
Workers通过兼容性标志支持众多Node.js API：
jsonc
// wrangler.jsonc
{
  "compatibility_flags": ["nodejs_compat_v2"],
  "compatibility_date": "2024-12-01"
}
nodejs_compat_v2支持的API：
  • crypto
    （大部分方法）
  • buffer
    （Buffer类）
  • util
    （promisify、类型相关）
  • stream
    （Readable、Writable）
  • events
    （EventEmitter）
  • path
    （所有方法）
  • string_decoder
  • assert
不支持的API（需使用替代方案）：
  • fs
    → 使用R2/KV
  • child_process
    → 无法使用
  • cluster
    → 不适用
  • dgram
    → 不支持
  • net
    → 使用fetch/WebSocket
  • tls
    → 由平台自动处理

When to Load References

何时加载参考文档

ReferenceLoad When
references/lambda-migration.md
Migrating AWS Lambda functions
references/vercel-migration.md
Migrating from Vercel/Next.js
references/express-migration.md
Migrating Express/Node.js apps
references/node-compatibility.md
Node.js API compatibility issues
参考文档加载场景
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兼容性问题时

Migration Checklist

迁移检查清单

  1. Analyze Dependencies: Check for unsupported Node.js APIs
  2. Convert to ESM: Replace require() with import
  3. Update Env Access: Use env parameter instead of process.env
  4. Replace File System: Use R2/KV for storage
  5. Handle Async: Use ctx.waitUntil() for background tasks
  6. Test Locally: Verify with wrangler dev
  7. Performance Test: Ensure CPU limits aren't exceeded
  1. 分析依赖项：检查是否存在不支持的Node.js API
  2. 转换为ESM：将require()替换为import
  3. 更新环境变量访问方式：使用env参数替代process.env
  4. 替换文件系统：使用R2/KV进行存储
  5. 处理异步任务：使用ctx.waitUntil()处理后台任务
  6. 本地测试：使用wrangler dev验证
  7. 性能测试：确保未超出CPU限制

See Also

另请参阅

  • workers-runtime-apis
    - Available APIs in Workers
  • workers-performance
    - Optimization techniques
  • cloudflare-worker-base
    - Basic Workers setup
  • workers-runtime-apis
    - Workers中可用的API
  • workers-performance
    - 优化技巧
  • cloudflare-worker-base
    - Workers基础设置