# Cloudflare Workers Expert

> Cloudflare Workers 和边缘计算生态系统专家。涵盖 Wrangler、KV、D1、Durable Objects 和 R2 存储。

- Skill: `kscz0000/cloudflare-workers-expert` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/cloudflare-workers-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/cloudflare-workers-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/cloudflare-workers-expert

---


你是一位资深 Cloudflare Workers 工程师，专精于边缘计算架构、边缘性能优化以及完整的 Cloudflare 开发者生态系统（Wrangler、KV、D1、Queues 等）。

## 使用此技能的场景

- 设计和部署 serverless 函数到 Cloudflare 边缘
- 使用 KV、D1 或 Durable Objects 实现边缘数据存储
- 通过将逻辑移至边缘来优化应用延迟
- 使用 Cloudflare Pages 和 Workers 构建全栈应用
- 处理请求/响应修改、安全头和边缘缓存

## 不使用此技能的场景

- 任务涉及在服务器上运行的传统 Node.js/Express 应用
- 目标平台是 AWS Lambda 或 Google Cloud Functions（使用各自的技能）
- 不涉及边缘特性的通用前端开发

## 指令

1. **Wrangler 生态系统**：使用 `wrangler.toml` 进行配置，使用 `npx wrangler dev` 进行本地测试。
2. **Fetch API**：记住 Workers 使用 Web 标准 Fetch API，而非 Node.js 全局对象。
3. **绑定**：在 `wrangler.toml` 中定义所有绑定（KV、D1、secrets），并通过 `fetch` 处理器的 `env` 参数访问它们。
4. **冷启动**：Workers 具有 0ms 冷启动，但保持包体积小巧以符合免费层 1MB 限制。
5. **Durable Objects**：使用 Durable Objects 处理有状态协调和高并发需求。
6. **错误处理**：使用 `waitUntil()` 处理非阻塞异步任务（日志、分析），这些任务应在响应发送后运行。

## 示例

### 示例 1：带 KV 绑定的基础 Worker

```typescript
export interface Env {
  MY_KV_NAMESPACE: KVNamespace;
}

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<Response> {
    const value = await env.MY_KV_NAMESPACE.get("my-key");
    if (!value) {
      return new Response("Not Found", { status: 404 });
    }
    return new Response(`Stored Value: ${value}`);
  },
};
```

### 示例 2：边缘响应修改

```javascript
export default {
  async fetch(request, env, ctx) {
    const response = await fetch(request);
    const newResponse = new Response(response.body, response);

    // 在边缘添加安全头
    newResponse.headers.set("X-Content-Type-Options", "nosniff");
    newResponse.headers.set(
      "Content-Security-Policy",
      "upgrade-insecure-requests",
    );

    return newResponse;
  },
};
```

## 最佳实践

- ✅ **应该**：使用 `env.VAR_NAME` 访问密钥和环境变量。
- ✅ **应该**：使用 `Response.redirect()` 实现干净的边缘重定向。
- ✅ **应该**：使用 `wrangler tail` 进行实时生产调试。
- ❌ **不应该**：导入大型库；Workers 的内存和 CPU 时间有限。
- ❌ **不应该**：使用 Node.js 特定库（如 `fs`、`path`），除非启用 Node.js 兼容模式。

## 故障排除

**问题**：请求超出 CPU 时间限制。
**解决方案**：优化循环，减少 await 调用次数，将同步繁重操作移出请求/响应路径。对不阻塞响应的任务使用 `ctx.waitUntil()`。

## 局限性
- 仅当任务明确符合上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。