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

§这份教程给你什么

你最终会得到这么一套能力：

01注册 Cloudflare 账号

五分钟的事，但有两个地方值得提前知道。

1. 打开注册页访问 dash.cloudflare.com/sign-up，填邮箱和密码。建议用 Gmail 或 Outlook，国内邮箱偶尔收不到 Cloudflare 的验证信。
2. 去邮箱点验证链接没验证的账号很多功能是灰的，别跳过。
3. 选 Free 计划它会引导你选套餐，一路选 Free（$0）。免费版对个人项目非常够用，具体额度看第 12 章。
4. 开启两步验证（强烈建议）右上角头像 → My Profile → Authentication → Two-Factor Authentication。这个账号后面会握着你的域名和线上服务，被盗很麻烦。
5. 记下 Account ID进 dash 后随便点进一个产品页，右侧栏或者地址栏里那串 32 位十六进制就是你的 Account ID，后面 GitHub 自动部署要用。

02把域名接进 Cloudflare

这一步的本质是：把域名的「解析权」从注册商交给 Cloudflare。交出去之后，你所有的 DNS 记录、CDN、证书、子域名都在 Cloudflare 后台管，Claude 也才能通过 MCP 看见它。

路线 A：你已经有域名

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

路线 B：你还没有域名

完全可以先不买。Cloudflare 会免费送你一个 你的用户名.workers.dev 的子域，部署上去就是 项目名.你的用户名.workers.dev，HTTPS 一样有，功能一模一样，只是网址长一点、不好记。先用它把整套流程跑通，喜欢了再买域名。

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

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，连上去走浏览器 OAuth 授权就行。

最省事的一条：先接这三个

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授权：让 MCP 真正能动你的账号

上一步只是「把线插上了」，还没「通电」。第一次用之前必须走一次 OAuth 授权，把你的 Cloudflare 账号权限授给它。

1. 启动 Claude Code在任意项目目录敲 claude。
2. 输入 /mcp会列出你刚才接的那几个服务器，状态多半是 needs authentication（需要认证）。
3. 选中要授权的那个，回车Claude Code 会自动拉起浏览器，打开 Cloudflare 的授权页面。
4. 在浏览器里确认页面会列出它要哪些权限（读 Worker、写 KV、读日志……），确认账号选对了（如果你有多个 Cloudflare 账号，这里一定看清楚选的是哪个），点 Approve / Allow。
5. 回到终端状态变成 connected 就成了。每个 MCP 服务器都要单独授权一次，三个就走三遍，之后长期有效，不用天天重来。

验证它真的通了

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

用 Cloudflare MCP 列一下我账号下现有的 Worker、KV 命名空间和 D1 数据库

如果它能报出你账号里的真实资源（新账号就是三个空列表，那也算通了——能返回空列表和「连不上」是两回事），说明整条链路打通了。

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

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

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

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

第一步：装并登录 wrangler

npx wrangler login    # 会拉起浏览器授权，点 Allow 即可
npx wrangler whoami   # 显示出你的邮箱和账号就是登录成功了

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

第二步：项目结构

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

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

{
  "name": "my-site",
  "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。

第三步：本地预览 + 部署

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

部署完终端会直接打印出网址，形如 https://my-site.你的用户名.workers.dev，点开就是全球可访问的线上站，HTTPS 已经配好了。到这里你已经有一个真实上线的网站了。

09绑上你自己的子域名

workers.dev 的网址能用但不好看。既然域名已经托管在 Cloudflare（第 2 章做完的话），绑子域名只要改配置文件加两行：

{
  "name": "my-site",
  "compatibility_date": "2026-08-19",
  "assets": { "directory": "./public" },

  "routes": [
    { "pattern": "blog.你的域名.com", "custom_domain": true }
  ]
}

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

想绑根域名（不带 www 的那个）也一样，pattern 直接写 你的域名.com。想两个都要就写两条。

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 my-db

# 2. 把它给你的 database_id 填进 wrangler.jsonc：
#    "d1_databases": [{ "binding": "DB", "database_name": "my-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 模板，生成后立刻复制保存，页面关掉就再也看不到了。
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. 绑自定义域名必须先迁 NS。只在 Cloudflare 加一条 CNAME 记录是不够的——整个域名的 NS 必须指向 Cloudflare，域名状态是 Active，custom_domain 才认。
2. R2 必须绑卡才能开。免费额度内不扣钱，但不绑卡这个产品对你完全不可见，会让你以为是自己配置错了。
3. 免费版不能对外发邮件。Workers 里 fetch 不到 SMTP 端口，Email Routing 只能收和转发。要发邮件走 Resend / Postmark 这类第三方 API。
4. 脚本大小上限 3MB（压缩后）。塞了大依赖（比如整包的图表库、Puppeteer）会直接部署失败。解决办法是把大资源丢 R2 或走 CDN，别打进 bundle。
5. wrangler 必须 4.x。配 GitHub Actions 时用 wrangler-action@v3 搭 3.x 的 wrangler，报错信息会指向完全无关的地方。
6. Actions 的 paths-ignore 别顺手忽略 **/*.md。如果你的站内容本身就是 Markdown 写的，这一条会导致「改了内容 push 上去却不部署」，排查半天。
7. TypeScript 项目要把 Worker 入口排除出前端的 tsconfig。否则前端构建会因为找不到 Cloudflare 的类型定义而报错，反之亦然。两套运行时，两套类型。
8. 静态资源默认对 .html 会去尾。访问 /about.html 可能被重定向到 /about。如果你的站是一堆手写 HTML 互相链接的，注意统一写法，或者显式配置 html_handling。
9. 缓存有时候咬人。部署完发现页面没变，先强刷（Cmd+Shift+R），还不行去 Cloudflare 后台 Caching → Purge Everything。给静态资源加内容哈希是根治办法。
10. 别把 API Token 提交进仓库。Cloudflare 会扫描公开仓库并自动吊销泄露的 Token，但你的账号在被吊销之前是裸奔的。Token 一律进 GitHub Secrets 或本地 .dev.vars（记得 gitignore）。

14可以直接抄的提示词

把这些原样发给 Claude Code，配合已经接好的 MCP，基本就是「说完等结果」。

① 从零建一个站并上线

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

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

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

③ 线上出问题时排查

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

④ 接 GitHub 自动部署

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

⑤ 让它先查文档再动手

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