文档评审清单

// 坏的文档：代码示例跑不通
// "使用以下代码创建用户："
// const user = createUser({ name: 'John' })  // createUser 不存在
 
// 好的文档：代码示例可运行
// "使用以下代码创建用户："
import { Hono } from 'hono'
 
const app = new Hono()
 
app.post('/users', async (c) => {
  const body = await c.req.json()
  const user = await c.env.DB.prepare('INSERT INTO users (name) VALUES (?)')
    .bind(body.name)
    .run()
  return c.json(user)
})
 
// 验证文档中的命令
// 文档说："运行以下命令部署"
// wrangler deploy  // 这个命令应该能跑通

## 部署步骤
 
### 前置条件
- 已安装 Node.js 18+
- 已安装 pnpm
- 已有 Cloudflare 账号
 
### 步骤 1：安装依赖
 
\`\`\`bash
pnpm install
\`\`\`
 
**预期结果**：看到 `Done in 2.5s`
 
### 步骤 2：配置环境变量
 
创建 `.env` 文件：
 
\`\`\`bash
cp .env.example .env
\`\`\`
 
编辑 `.env`，填入你的 Cloudflare API Token：
 
\`\`\`
CLOUDFLARE_API_TOKEN=your_token_here
\`\`\`
 
**获取 Token**：登录 Cloudflare Dashboard → My Profile → API Tokens → Create Token
 
### 步骤 3：部署
 
\`\`\`bash
pnpm deploy
\`\`\`
 
**预期结果**：看到 `Deployed to https://my-app.workers.dev`
 
### 步骤 4：验证
 
访问 https://my-app.workers.dev，应该看到 "Hello World"
 
**如果失败**：
- 检查 API Token 是否正确
- 检查网络连接
- 运行 `wrangler tail` 查看日志

## 坏的排版
使用Hono框架开发Cloudflare Workers应用,需要Node.js18+版本。
 
## 好的排版
使用 Hono 框架开发 Cloudflare Workers 应用，需要 Node.js 18+ 版本。
 
规则：
- 中英文之间加空格：使用 Hono 框架
- 数字与中文之间加空格：Node.js 18+ 版本
- 使用中文标点：，。、；：""''
- 专有名词保持原样：Node.js、Cloudflare、Workers

---
title: 部署指南
author: 白川
createdAt: 2026-01-01
updatedAt: 2026-06-21
maintainer: @zhangsan
review_cycle: 6 months
---
 
# 部署指南
 
## 更新记录
- 2026-06-21 更新部署命令（wrangler v3）
- 2026-03-15 添加故障排查章节
- 2026-01-01 初始版本
 
## 反馈问题
如果发现文档有误，请：
1. 提 Issue：https://github.com/xxx/docs/issues
2. 或联系维护者 @zhangsan

## POST /api/v1/users
 
创建新用户。
 
### 认证
需要 Bearer Token（管理员权限）
 
### 请求
 
**Headers**
\`\`\`
Authorization: Bearer <token>
Content-Type: application/json
\`\`\`
 
**Body**
\`\`\`json
{
  "name": "张三",
  "email": "[email protected]",
  "role": "user"
}
\`\`\`
 
**字段说明**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 用户姓名，1-100 字符 |
| email | string | 是 | 邮箱地址，必须唯一 |
| role | string | 否 | 角色，默认 "user"，可选 "admin" |
 
### 响应
 
**201 Created**
\`\`\`json
{
  "id": "usr_abc123",
  "name": "张三",
  "email": "[email protected]",
  "role": "user",
  "createdAt": "2026-06-21T10:00:00Z"
}
\`\`\`
 
**400 Bad Request**
\`\`\`json
{
  "code": "VALIDATION_ERROR",
  "message": "请求参数校验失败",
  "details": [
    { "field": "email", "message": "邮箱格式不正确" }
  ]
}
\`\`\`
 
**409 Conflict**
\`\`\`json
{
  "code": "EMAIL_EXISTS",
  "message": "邮箱已被注册"
}
\`\`\`
 
### 限流
- 每用户每分钟 10 次
- 超限返回 429 Too Many Requests
 
### 示例
 
**curl**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "email": "[email protected]"}'
\`\`\`