把 Cloudflare 接进 Claude Code
然后让它替你把网站建起来

§你现在的起点

Leo 把你加进了他的 Cloudflare 账号，并且把 zdtthaikovsky.org 这个域名放在里面给你用。翻译成人话：

01接受邀请，进入账号

邮箱里会有一封来自 Cloudflare 的邀请邮件，标题大致是 「You have been added to an account」 或中文的「您已被添加到账户」。

1. 点邮件里的 Accept / 接受找不到就翻垃圾箱，Cloudflare 的信偶尔被误判。也可以直接去 dash.cloudflare.com，登录后在右上角看有没有待处理的邀请。
2. 用被邀请的那个邮箱注册或登录如果你还没有 Cloudflare 账号，它会让你就地设个密码把账号建起来——必须用收到邀请的那个邮箱，换一个就对不上了。
3. 验证邮箱没验证的账号很多功能是灰的，别跳过。
4. 开两步验证右上角头像 → My Profile → Authentication → Two-Factor Authentication。这个账号里有别人的线上服务，被盗是连坐的，麻烦花两分钟开一下。
5. 确认你看到了正确的账号登录后左上角有账号切换器。你应该能看到一个不是你自己名字的账号（Leo 的账号），点进去，域名列表里有 zdtthaikovsky.org，就对了。
6. 记下 Account ID随便点进一个产品页，右侧栏能看到一串 32 位的十六进制，那是 Account ID。后面配自动部署要用，先复制到备忘录里。

02账号里有什么，以及几条规矩

这是个共用账号，进去之后你会看到不止你的东西。花一分钟建立正确的认知，比之后误删了再补救省事得多。

你看到的域名

三条规矩

• 只在 zdtthaikovsky.org 下面折腾。建 Worker、加 DNS 记录、绑域名，全部限定在这个域名里。看到别的域名下有 DNS 记录、Worker、页面规则，路过就好。
• 给自己的东西起带前缀的名字。Worker 名字建议统一加个 zdt- 前缀，比如 zdt-blog、zdt-api。这样账号里一眼能看出哪些是你的，你自己删起来也不会手抖删错。
• 删东西之前多看一眼。Cloudflare 的删除大多没有回收站。删 Worker、删 D1 数据库、删 R2 桶，删完就没了。看清楚名字再点。

你有哪些权限

你拿到的是 Administrator（管理员）角色：建 Worker、改 DNS、绑域名、开 D1 / R2 / KV、看日志——教程里的每一步你都做得了。

够不到的只有两类：账单相关（升级套餐、绑卡、看发票）和成员管理（拉人、改别人权限）。这两类是 Super Administrator 才有的。所以如果你点某个按钮发现是灰的、或者提示权限不足，八成就是撞上这两条了，找 Leo 就行，不是你操作错了。

03装好 Claude Code

已经在用的话跳到第 4 章。没装的话：

curl -fsSL https://claude.ai/install.sh | bash

Windows 建议装在 WSL2（Ubuntu）里，体验和 macOS 一致；纯 Windows 下 wrangler 和整条 Node 工具链的坑会多不少，不值得跟它较劲。

装完在项目目录里敲 claude 启动，第一次会让你登录 Anthropic 账号。顺手确认一下 Node 版本，Cloudflare 的工具链要 Node 20 以上：

node -v      # 要 v20 或更高，低了去 nodejs.org 装 LTS 版
claude --version

04先搞懂 MCP 是什么

MCP 全称 Model Context Protocol（模型上下文协议），Anthropic 定的一个开放标准。一句话解释：

具体到 Cloudflare，连上之后 Claude 就能做这些事，不用你复制粘贴任何东西给它：

• 列出账号下所有 Worker、KV 命名空间、D1 数据库、R2 存储桶
• 直接对 D1 数据库执行 SQL（建表、查数据、改数据）
• 拉线上 Worker 的实时日志和报错，帮你定位 500 到底是哪一行抛的
• 查 Cloudflare 官方文档的最新写法（这点比它凭记忆瞎写靠谱得多）
• 看 CI 构建记录，构建失败时直接读构建日志

05把 Cloudflare MCP 接进 Claude Code

Cloudflare 官方提供的是 远程 MCP 服务器（Remote MCP）——不用在本地跑任何服务、不用装 Docker、不用手工填 API Token，连上去走浏览器授权就行。

先接这三个就够

Cloudflare 一共开了十几个 MCP 服务器，不要一次全接——接太多会占掉 Claude 的上下文，反而变笨。刚上手接下面三个：

# 1. 官方文档：让 Claude 写 Cloudflare 代码前先查文档，别凭记忆瞎编
claude mcp add --scope user --transport http cf-docs https://docs.mcp.cloudflare.com/mcp

# 2. Workers 资源：列 Worker / 建 KV / 建 D1 / 建 R2 / 直接跑 SQL
claude mcp add --scope user --transport http cf-bindings https://bindings.mcp.cloudflare.com/mcp

# 3. 可观测性：拉线上日志和报错，排查线上 bug 全靠它
claude mcp add --scope user --transport http cf-observability https://observability.mcp.cloudflare.com/mcp

--scope user 的意思是装在你的用户级配置里，以后在任何项目目录打开 Claude Code 都能用，不用每个项目重接一遍。

全部可选的服务器

需要哪个再加哪个，命令格式完全一样，只换名字和 URL：

接错了怎么删

claude mcp list                            # 看已经接了哪些、连上没有
claude mcp remove cf-radar --scope user    # 删掉不想要的

06授权：这一步最容易选错账号

上一步只是「把线插上了」，还没「通电」。第一次用之前必须走一次 OAuth 授权。

1. 启动 Claude Code在任意项目目录敲 claude。
2. 输入 /mcp会列出你刚接的那几个服务器，状态多半是 needs authentication（需要认证）。
3. 选中要授权的那个，回车Claude Code 会自动拉起浏览器，打开 Cloudflare 的授权页。
4. ⚠️ 在浏览器里选对账号如果你名下有多个 Cloudflare 账号，授权页会让你选择要授权哪个账号。一定要选 Leo 那个账号（不是你自己新建的那个空账号）——zdtthaikovsky.org 在它下面。选错了后面 Claude 会告诉你「账号里什么都没有」，你会以为是没连上，其实是连到了空账号。
5. 确认权限，点 Approve页面会列出它要哪些权限（读 Worker、写 KV、读日志……），确认后回到终端。
6. 状态变 connected 就成了每个 MCP 服务器都要单独授权一次，三个就走三遍。之后长期有效，不用天天重来。

验证它真的通了

回到 Claude Code 的对话里，直接用大白话问它：

用 Cloudflare MCP 列一下这个账号下现有的 Worker，
以及 zdtthaikovsky.org 这个域名下已经绑了哪些子域名

如果它能报出 zdt-cf-guide 这个 Worker（就是你正在看的这个站）和 zdtthaikovsky.org，说明整条链路通了，而且账号选对了。如果它说什么都没有，回去重新授权，账号选错了。

07接上之后，具体能让它干什么

下面这些话可以直接原样发给 Claude Code，它会自己调 MCP 完成：

08实战：十分钟上线你的第一个站

目标：把一个纯静态网页（手写的 HTML/CSS/JS，或者 Vite、Next、Astro 构建出来的产物）变成一个真实可访问的网址。

第一步：登录 wrangler

npx wrangler login    # 拉起浏览器授权，点 Allow
npx wrangler whoami   # 看看你能操作哪些账号

用 npx wrangler 而不是全局安装，这样每个项目用自己 package.json 里锁定的版本，不会因为版本漂移出奇怪的问题。

第二步：项目结构

最小可用的静态站就三个文件：

zdt-blog/
├── public/
│   └── index.html      # 你的网页放这里
├── package.json
└── wrangler.jsonc      # Cloudflare 的部署配置

{
  "name": "zdt-blog",
  "account_id": "你的 Account ID",
  "compatibility_date": "2026-08-19",
  "assets": {
    "directory": "./public",
    "not_found_handling": "single-page-application"
  }
}

assets 这一段是关键，意思是「把 public 目录当静态资源直接对外服务」。not_found_handling 设成 single-page-application，找不到的路径会回落到 index.html——React/Vue 这类前端路由必须这么配，否则刷新子页面会 404。

name 记得带 zdt- 前缀，这是第 2 章说的规矩。

第三步：本地预览 + 部署

npx wrangler dev      # 本地起服务，浏览器开 localhost:8787 看效果
npx wrangler deploy   # 一条命令上线

部署完终端会直接打印出网址。到这里你已经有一个真实上线、全球可访问、HTTPS 配好的网站了。下一章把它换成好看的域名。

09绑上你自己的子域名

这是最爽的一步，也是最简单的一步。域名的解析权已经在 Cloudflare 手里了（这就是 Leo 帮你省掉的那一大坨活儿），所以绑子域名只要改配置文件加两行：

{
  "name": "zdt-blog",
  "account_id": "你的 Account ID",
  "compatibility_date": "2026-08-19",
  "assets": { "directory": "./public" },

  "routes": [
    { "pattern": "blog.zdtthaikovsky.org", "custom_domain": true }
  ]
}

然后再 npx wrangler deploy。就这样——不用去 DNS 后台手动加 CNAME 记录，custom_domain: true 会让 Cloudflare 自动建好解析、自动签发证书。等一两分钟证书就绪，https://blog.zdtthaikovsky.org 就能打开了。

10加后端：Cloudflare 全家桶怎么用

静态站上线之后，真正的乐趣是加后端。Cloudflare 的做法叫 绑定（bindings）：在配置文件里声明你要用哪个资源，代码里就能通过一个变量直接访问，不需要连接串、不需要密码、不需要装 SDK。

Workers：写后端接口

在项目根目录建 src/index.js，配置里加 "main": "src/index.js"：

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // 一个最简单的 API 接口
    if (url.pathname === "/api/hello") {
      return Response.json({ msg: "你好，我是跑在全球边缘节点上的后端" });
    }

    // 其他路径交给静态资源处理
    return env.ASSETS.fetch(request);
  }
};

D1：SQLite 数据库

# 1. 建库（也可以直接让 Claude 通过 MCP 建，更省事）
npx wrangler d1 create zdt-blog-db

# 2. 把它返回的 database_id 填进 wrangler.jsonc：
#    "d1_databases": [{ "binding": "DB", "database_name": "zdt-blog-db", "database_id": "xxx" }]

# 3. 代码里直接用，不需要连接串、不需要密码：
#    const { results } = await env.DB.prepare("SELECT * FROM posts").all();

其余几件套

11让它 push 一次就自动部署

手动敲 wrangler deploy 久了会烦，而且容易忘。正确姿势是接 GitHub Actions：你只管 push 到 main，剩下自动完成。

1. 准备一个 API TokenCloudflare 后台 → 右上角头像 → API Tokens → Create Token，选 Edit Cloudflare Workers 模板。创建时注意 Account Resources 选的是 Leo 那个账号，别选成你自己的。生成后立刻复制保存，页面关掉就再也看不到了。
2. 写进 GitHub 仓库的 Secrets仓库 → Settings → Secrets and variables → Actions → New repository secret，建两条：CLOUDFLARE_API_TOKEN（刚才那串）和 CLOUDFLARE_ACCOUNT_ID（第 1 章记下的那串）。
3. 加工作流文件把下面这段存成 .github/workflows/deploy.yml。
4. push 到 main去仓库 Actions 页签看它跑，绿了就是上线了。

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]
  workflow_dispatch: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy

12速查表与免费额度

免费版对个人项目的实际感受是：只要你不是做爆款产品，基本一辈子花不到钱。但记住这些额度是整个账号共享的，不是你一个人的。

13会浪费你半天的十个坑

都是实打实踩过的，提前看一眼能省很多时间。前三条是你这种「共用账号」身份特有的。

1. 账号选错，是你最可能遇到的问题。MCP 授权页、wrangler login、创建 API Token、网页 dashboard——四个地方都会让你选账号。选成你自己的空账号时不会有任何报错，只是东西建到了另一边，你会对着空列表怀疑人生。根治办法：在 wrangler.jsonc 里写死 account_id。
2. 按钮是灰的，多半不是你的错。账单、升级套餐、加成员这些是 Super Administrator 专属，你是 Administrator，够不着。撞上了找 Leo，别在那儿反复试。
3. R2 要账号级绑卡才能开。不绑卡这个产品对你完全不可见，会让你以为是自己配置错了。要用先问 Leo 开没开。
4. 绑域名只能绑 zdtthaikovsky.org 下面的。别的域名是 Leo 的线上服务，绑上去等于把人家的站顶掉。根域和 www 也别占，那是这份教程站。
5. 免费版不能对外发邮件。Workers 里 fetch 不到 SMTP 端口，Email Routing 只能收和转发。要发邮件走 Resend / Postmark 这类第三方 API。
6. 脚本大小上限 3MB（压缩后）。塞了大依赖（整包的图表库、Puppeteer 之类）会直接部署失败。解决办法是把大资源丢 R2 或走 CDN，别打进 bundle。
7. wrangler 必须 4.x。配 GitHub Actions 时用 wrangler-action@v3 搭 3.x 的 wrangler，报错信息会指向完全无关的地方。
8. Actions 的 paths-ignore 别顺手忽略 **/*.md。如果你的站内容本身就是 Markdown 写的，这条会导致「改了内容 push 上去却不部署」，排查半天。
9. 缓存有时候咬人。部署完发现页面没变，先强刷（Cmd+Shift+R / Ctrl+F5），还不行去 Cloudflare 后台 Caching → Purge Everything。给静态资源加内容哈希是根治办法。
10. 别把 API Token 提交进仓库。Cloudflare 会扫描公开仓库并自动吊销泄露的 Token，但在被吊销之前，那把钥匙能动的是整个账号，包括 Leo 的东西。Token 一律进 GitHub Secrets 或本地 .dev.vars（记得写进 gitignore）。

14可以直接抄的提示词

把这些原样发给 Claude Code，配合已经接好的 MCP，基本就是「说完等结果」。记得把 Account ID 换成你自己记下的那串。

① 从零建一个站并上线

我要做一个个人主页，纯静态就行，深色风格，放我的简介、项目列表和联系方式。
做完部署到 Cloudflare Workers，用 static assets 方式，
Worker 名字用 zdt- 开头，account_id 写死成 xxx，
然后绑到 me.zdtthaikovsky.org 这个子域名上。
配置文件里的注释用中文写。

② 给现有项目加后端和数据库

给这个项目加一个留言板功能：
用 Cloudflare D1 建库建表（通过 MCP 建，别让我手动去后台点），
写好 POST 提交和 GET 读取两个接口，前端加个简单的表单，
加上 Turnstile 人机验证防刷，最后部署上去。

③ 线上出问题时排查

我的 Worker 叫 zdt-xxx，刚才访问返回 500。
用 Cloudflare 的 observability MCP 拉最近的日志，
定位到具体是哪一行出的问题，然后直接改掉并重新部署。

④ 接 GitHub 自动部署

把这个项目接上 GitHub Actions 自动部署到 Cloudflare：
建仓库、写 workflow 文件、告诉我需要去 GitHub 配哪几个 Secret，
以后我 push 到 main 就自动上线，不用再手动 deploy。

⑤ 让它先查文档再动手

先用 cf-docs MCP 查一下 Cloudflare 官方现在推荐的写法，
确认清楚 API 没变之后再动手写，别凭记忆写过时的用法。

附以后想自立门户

等你玩顺了，大概率会想要一个完全属于自己的账号和域名。这一节是那时候看的，现在可以跳过。

自己注册账号

去 dash.cloudflare.com/sign-up 用另一个邮箱注册，选 Free 计划。整套流程跟这份教程完全一样，唯一多出来的是下面这步——把域名接进去，也就是 Leo 已经帮你做掉的那部分。

把域名接进 Cloudflare

本质是把域名的解析权从注册商交给 Cloudflare。交出去之后，DNS、CDN、证书、子域名才全部归 Cloudflare 管。

1. 添加站点Dashboard 左上角 Add a domain，输入域名（只填 example.com，不要带 www 和 https），选 Free 计划，它会自动扫描你现有的 DNS 记录。
2. 拿到两个 NS 地址形如 josephine.ns.cloudflare.com。每个账号拿到的这一对都不一样，一定用你自己页面上显示的那一对。
3. 回注册商改 NS登录你买域名的地方，找到「DNS 服务器 / Nameservers」，把原来的两条删掉换成 Cloudflare 给你的那两条。
4. 等生效快则十几分钟，慢则几小时（极端 24 小时）。后台状态从 Pending 变绿色 Active 就成了。

买域名去哪

.org / .com 一年几十到一百块。推荐 Spaceship、NameSilo——便宜、改 NS 方便。国外注册商 + Cloudflare 托管的组合不需要 ICP 备案，这也是为什么这条路适合个人练手。

另外，不买域名也能玩：Cloudflare 免费送你一个 你的用户名.workers.dev 子域，部署上去就是 项目名.你的用户名.workers.dev，HTTPS 一样有，功能一模一样，只是网址长一点。