
---

## 一、准备工作

在开始之前，请确保你已经具备以下条件：

### 1️⃣ Cloudflare 账号
- 注册地址：https://dash.cloudflare.com/
- 登录后能进入 **Dashboard**

### 2️⃣ Node.js 环境
- **推荐版本：Node.js ≥ 18**
- 检查是否已安装：

```bash
node -v
npm -v
```

未安装可前往：https://nodejs.org/

---

## 二、安装 Wrangler CLI

Wrangler 是 Cloudflare 官方提供的 Worker 开发与部署工具。

### 全局安装（推荐）

```bash
npm install -g wrangler
```

安装完成后检查版本：

```bash
wrangler --version
```

---

## 三、登录 Cloudflare

使用 Wrangler 登录你的 Cloudflare 账号：

```bash
wrangler login
```

- 浏览器会自动打开授权页面
- 授权成功后，CLI 会显示登录完成

> 💡 登录信息会保存在本地，无需每次重复登录

---

## 四、创建 Worker 项目

### 方式一：使用官方模板（推荐）

```bash
wrangler init my-worker
```

执行后会：
- 创建项目目录
- 生成 `wrangler.toml`
- 初始化示例 Worker

进入项目目录：

```bash
cd my-worker
```

---

## 五、项目结构说明

典型 Worker 项目结构如下：

```text
my-worker/
├─ src/
│  └─ index.ts        # Worker 入口文件
├─ wrangler.toml      # Wrangler 配置文件
├─ package.json
└─ tsconfig.json
```

---

## 六、编写第一个 Worker

编辑 `src/index.ts`：

```ts
export default {
  async fetch(request: Request): Promise<Response> {
    return new Response("Hello Cloudflare Workers! 🚀", {
      headers: { "content-type": "text/plain" },
    })
  },
}
```

---

## 七、本地开发与调试

Wrangler 提供本地开发服务器：

```bash
wrangler dev
```

- 默认监听 http://localhost:8787
- 修改代码后自动热更新

---

## 八、部署到 Cloudflare

一行命令即可部署：

```bash
wrangler deploy
```

部署成功后你会看到类似输出：

```text
Uploaded my-worker
Deployed my-worker
https://my-worker.your-name.workers.dev
```

🎉 打开该 URL 即可访问你的 Worker！

---

## 九、wrangler.toml 核心配置说明

示例：

```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
```

常用字段说明：

| 字段 | 说明 |
|----|----|
| name | Worker 名称 |
| main | 入口文件 |
| compatibility_date | Worker 运行兼容日期 |
| workers_dev | 是否启用 *.workers.dev |

---

## 十、常见问题

### ❓ deploy 失败 / 没权限
- 确认已执行 `wrangler login`
- 确认当前账号下有 Worker 权限

### ❓ 端口被占用

```bash
wrangler dev --port 3000
```

---

## 十一、进阶方向

- 绑定 KV / D1 / R2
- 使用环境变量（`[vars]`）
- 多环境部署（dev / prod）
- 使用 Durable Objects


