把网站部署到 Cloudflare Pages · 从注册到 AI 自动化

为什么选 Cloudflare Pages
开始前的准备
先选路线：四种部署方式对比
路线一：拖拽上传（最快，零配置）
路线二：Git 集成（自动部署，长期首选）
路线三：Wrangler 命令行
路线四：用 AI 完成部署（自动化）
绑定自定义域名
Pages 与 Workers 的关系（重要）
常见问题排查

Why

为什么选 Cloudflare Pages

市面上的免费托管不少，但 Pages 有几个实打实的优势。

维度	Cloudflare Pages	Vercel	Netlify	GitHub Pages
费用	免费额度充足	免费（100GB 流量）	免费（100GB）	免费
全球 CDN	Cloudflare 全网	快	中	节点少
私有仓库	支持	支持	支持	免费版不支持
商用 / 电商	明确允许	免费版条款较严	视计划而定	官方禁止
HTTPS 证书	自动签发	自动	自动	需手动
构建额度	充足	较严	300 分钟/月	10 次/小时
AI 原生部署	官方 MCP + Skills	有限	有限	无

✓

关键结论：纯静态站点（HTML / CSS / JS，或框架构建后的产物）非常适合 Pages。部署结果是 https://你的项目名.pages.dev，全球 CDN 加速，HTTPS 自动配好，完全免费。

Setup

开始前的准备

两样东西就够：一个 Cloudflare 账号，和一份"已经能本地跑起来"的网站文件。

1. 注册 Cloudflare 账号

打开注册页，用邮箱创建账号

访问 dash.cloudflare.com/sign-up，填写邮箱和密码，验证邮箱后进入控制台。

选 Free 免费套餐（默认就是这个）
不需要绑定信用卡
中途会问是否购买域名 / 迁移 DNS，全部跳过即可，纯托管静态站不需要域名也能上线

2. 确认你要上传的是"构建产物"

这是新手最容易踩的坑：Cloudflare 要的不是源码，而是网站最终的文件。也就是说根目录必须有 index.html。

你的项目类型	该上传哪个目录	先执行什么
纯手写 HTML / CSS / JS	`项目根目录`	无需构建，直接传
Vue / Vite	`dist/`	`npm run build`
React（CRA）	`build/`	`npm run build`
Next.js（静态导出）	`out/`	`next build` 后设 `output: 'export'`
Astro	`dist/`	`npm run build`
Hugo	`public/`	`hugo`
uni-app / 微信小程序（不适用）	小程序代码不能直接部署到 Pages，需要先转成 H5

项目结构示例（纯静态）

# 传之前先在本地双击 index.html 确认能正常显示
my-site/
├── index.html          # 必须有，且在第一层
├── about.html
├── css/
│   └── style.css
├── js/
│   └── main.js
└── images/
    └── logo.png

# 常见错误：把上一级文件夹拖进去，会导致 404
# 正确做法：进入 my-site 内部，全选所有文件再拖

上传前自检清单：

构建输出目录里有 index.html
本地用 python3 -m http.server 8000 能正常打开
单文件没超过 25 MiB，文件总数没超（见下方限制表）
路径引用都是相对路径（不要写 /Users/你的名字/... 这种绝对路径）

3. 拖拽上传的硬性限制

上传方式	文件数量上限	单文件大小上限	支持 ZIP
控制台拖拽	1,000 个	25 MiB	支持
Wrangler CLI	20,000 个	25 MiB	不支持，需先解压

如果你的站点资源多（图片、视频、字体多），直接跳过路线一，用命令行或 Git。

Choose

先选路线：四种部署方式

不用都学，按你的场景挑一条走完就行。后面每条路线都有完整步骤。

最快 · 5 分钟

① 拖拽上传

打开控制台，把文件夹拖进去就完事了。适合一次性的小站、演示页面、想快速看到效果的人。

零配置不需要 Git ≤1000 文件

长期首选

② Git 集成

连上 GitHub / GitLab，之后每次 git push 自动部署，每次 PR 自动生成预览环境。

自动部署预览分支可回滚

灵活 · 需命令行

③ Wrangler CLI

本地一条命令上传，支持自定义分支、CI 自动化，文件数上限更高（20000）。

CI/CD 友好可脚本化 ≤20000 文件

最省事 · 自动化

④ AI 部署

接入 Cloudflare 官方 MCP / Skills，在 AI 编程工具里说一句"帮我部署"，它自己完成上传并返回网址。

一句话搞定 Claude / Cursor / Codex 官方支持

怎么选？

只想试一下 / 交作业 → 路线 ①，拖拽 3 分钟搞定
自己维护的项目，要长期迭代 → 路线 ②，之后每个改动自动上线
文件多、或要接 CI → 路线 ③
平时就用 AI 写代码 → 路线 ④，把部署也交给 AI，你什么都不用改

Route 01

路线一：拖拽上传

不需要装任何东西，全程鼠标操作。这是验证"我的网站能不能上线"最快的方式。

进入 Pages 创建页

登录控制台后，从左侧导航进入 Workers & Pages，点 Create application，选择 Pages 标签页，然后点 Get started。

如果看到 Drag and drop your files 选项，说明走对了。

起个项目名

项目名会成为你的默认网址：https://项目名.pages.dev。只能用小写字母、数字、连字符。

起名技巧：名字一旦确定很难改（要删项目重建）。想清楚再填。名字冲突时 Cloudflare 会自动加随机后缀。

把文件夹拖进去

把准备好的构建产物文件夹（或它的 ZIP 压缩包）拖进虚线框。注意：拖的是文件夹本身，不是它的父目录。

✗ 错误：拖了 Desktop → 网站里出现 my-site/index.html → 访问报 404 ✓ 正确：拖了 my-site 文件夹 → 根目录直接就是 index.html

点 Deploy site

上传完成后点 Deploy site，等待 30–60 秒。构建日志会实时显示，成功后自动跳转到你的站点。

✓ 部署成功

https://你的项目名.pages.dev

怎么更新？在项目页点 Create a new deployment → 选择目标环境（Production 生产 / Preview 预览）→ 重新拖入文件。可以选择新建分支或填已有分支名。

限制提醒：控制台拖拽不支持编译 functions/ 目录（Pages Functions）。如果你有边缘函数，只能用 Wrangler 上传。单个文件超 25 MiB 会标红且无法上传，只能删掉后重新传整个项目。

Route 02

路线二：Git 集成（自动部署）

连一次 GitHub，之后每次 push 自动上线。这是长期维护项目的正确姿势。

前置条件

网站代码已经推送到 GitHub / GitLab 仓库（私有仓库也可以）
项目根目录里有 package.json，且 scripts.build 已配好（纯静态站可跳过）

连接 Git 账号

Workers & Pages → Create application → Connect to Git（或从已有项目进 Settings → Git）。点 Connect GitHub / Connect GitLab，在弹窗里授权。

授权时可只勾选需要的仓库，之后可以随时调整。

选择仓库

从列表里选你的仓库。私有仓库只要授权过就能看到。

配置构建设置

Cloudflare 会自动识别框架并预填，但你要逐项确认这几个关键字段：

字段	说明	建议值
Project name	决定 `.pages.dev` 域名	同域名，不要用下划线
Production branch	哪个分支的提交算"正式发布"	`main`
Framework preset	预构建命令和输出目录	按实际框架选
Build command	安装依赖后执行的命令	纯静态站留空
Build output directory	构建产物的目录	静态站填 `/` 或 `.`
Root directory	仓库里子项目的路径	monorepo 才需要填，如 `apps/web`
Environment variables	构建时注入的环境变量	区分 Production / Preview 两套

点 Save and Deploy

Cloudflare 会 clone 仓库、安装依赖、跑构建、上传产物。1–3 分钟完成，期间可以看实时构建日志。日志报错先别慌，对照下面的排查表。

几个值得知道的机制

预览部署（Preview）

任何非生产分支的 push，都会得到一个独立的预览网址，格式是 https://<commit>.项目名.pages.dev，或 https://<分支名>.项目名.pages.dev。PR 可以自动在评论里贴出预览链接。

用法：做完一个新功能，先推到 feature/xxx 分支看看效果，确认没问题再合并到 main。不用担心把生产环境搞坏。

自动注入的环境变量

构建时可用的变量

CF_PAGES=1                # 在 Pages 环境里恒为 1
CI=true                    # CI 环境标志
CF_PAGES_BRANCH=main         # 当前分支名
CF_PAGES_COMMIT_SHA=a1b2c3d   # 提交哈希
CF_PAGES_URL=https://xxx.pages.dev   # 生产环境地址

判断环境的小技巧：代码里写 if (process.env.CI === "true") { /* 预览环境 */ } 就能在预览地址上展示调试信息，不影响生产。

✓

回滚：项目页 Deployments 里能看到每一次部署记录，点任意历史版本右边的 ⋯ 就能一键回滚（Promotion）。改坏了不用慌。

Route 03

路线三：Wrangler 命令行

文件多、要接 CI、或者想本地先预览效果时用这条。5 条命令搞定。

不需要全局安装。下面统一用 npx 调用，它会临时拉取最新的 wrangler，省去版本管理麻烦。需要 Node.js 18+。

步骤

登录 Cloudflare

Terminal

# 会自动打开浏览器，让你点授权
npx wrangler login

如果 CI 环境无法开浏览器，改用 API Token 环境变量：

CI / 服务器环境

export CLOUDFLARE_ACCOUNT_ID=你的账户ID
export CLOUDFLARE_API_TOKEN=你的API令牌

# 令牌在 dash.cloudflare.com/profile/api-tokens 创建
# 权限选 Account → Cloudflare Pages → Edit

创建项目（只需一次）

Terminal

npx wrangler pages project create

交互式提问：项目名、生产分支。这两个值会被缓存到 node_modules/.cache/wrangler，后续部署自动复用。

本地先预览（强烈建议）

Terminal

npx wrangler pages dev ./dist

# 默认 http://localhost:8788

本地模拟边缘运行时，能提前发现 404、资源路径错误等问题。改完用 Ctrl + C 退出。

部署到生产环境

Terminal

# 把 ./dist 换成你的构建产物目录
npx wrangler pages deploy ./dist

✓ 部署成功

https://项目名.pages.dev

部署到预览分支（可选）

Terminal

npx wrangler pages deploy ./dist --branch=staging

# 预览地址：https://staging.项目名.pages.dev

常用管理命令

速查表

# 查看所有 Pages 项目
npx wrangler pages project list

# 查看某个项目的所有部署（每次的独立 URL）
npx wrangler pages deployment list --project-name=my-site

# 实时查看访问日志
npx wrangler pages deployment tail --project-name=my-site

# 删除项目（会连同所有部署一起删，谨慎）
npx wrangler pages project delete

# 从零脚手架：选框架 + 自动部署（强烈推荐）
npm create cloudflare@latest -- --platform=pages

✓

新项目强烈建议用 C3 脚手架：npm create cloudflare@latest -- --platform=pages 会引导你选框架（Vue / React / Astro / Next.js / Nuxt / SvelteKit / Hono 等），自动生成配置并询问是否直接部署，一步到位。

注意：不写 --platform=pages 的话，C3 默认创建的是 Workers 项目，不是 Pages。

Route 04

路线四：用 AI 完成部署

这是最省事的一条：不打开控制台，不敲命令，在 AI 编程工具里说一句"帮我部署"，AI 自己完成建项目、传文件、返回网址。

Cloudflare 官方提供 托管的远程 MCP Server 和 Skills 插件。连上之后，AI 编程助手就能读到你 Cloudflare 账户的信息、给出部署建议，并直接替你执行变更。支持 Claude Code、Cursor、Windsurf、OpenCode、Codex、Pi 等任何兼容 MCP / Agent Skills 的客户端。

方式 A：接入 Cloudflare API MCP Server（推荐）

这是覆盖最全的方式，一个 Server 打通 Cloudflare 全 API（2500+ 端点）。配置只要几行：

MCP 客户端配置

{
  "mcpServers": {
    "cloudflare-api": {
      "url": "https://mcp.cloudflare.com/mcp"
    }
  }
}

添加配置

把上面这段加到你所用客户端的 MCP 配置里。WorkBuddy 里就是写到 ~/.workbuddy/mcp.json。

在客户端里点连接并授权

连接后会跳转到 Cloudflare 页面让你登录并选择授权范围（OAuth）。授权完成后，MCP 就活了 —— 能读你的账户、项目、部署记录。

关于它的设计：只暴露 search() 和 execute() 两个工具，而不是 2594 个。AI 会针对 OpenAPI 结构现场写 JS 代码去调用，执行在隔离沙箱里。上下文占用约 1000 tokens，而不是 100 万 —— 这是它相比原生 MCP 的核心优势。

让 AI 部署

授权好后，直接对 AI 说：

✓

可以直接复制给 AI 的指令：

帮我把这个网站部署到 Cloudflare Pages。
项目名用 my-project，产物目录是 ./dist。
部署完把访问地址发给我。

AI 会自己去确认构建产物、判断框架、调用 API 完成部署，最后把 https://xxx.pages.dev 给你。

方式 B：安装 Cloudflare Skills 插件

如果你的 AI 工具支持 Agent Skills 标准，装插件更省事（自带 MCP + 上下文知识 + 斜杠命令）：

各客户端安装命令

# Claude Code —— 插件市场
/plugin marketplace add cloudflare/skills

# 通用 —— npx skills CLI
npx skills add https://github.com/cloudflare/skills

# Cursor —— 也可以手动添加远程规则
# Settings → Rules → Add Rule → Remote Rule (GitHub)

# 手动克隆到技能目录：
# Claude Code  ~/.claude/skills/
# Cursor      ~/.cursor/skills/
# OpenCode    ~/.config/opencode/skills/
# Codex       ~/.codex/skills/
# Pi ~/.pi/agent/skills/

其他有用的官方 MCP Server

按需再接，不用全装：

用途	Server 地址
查 Cloudflare 官方文档（最新版）	`https://docs.mcp.cloudflare.com/mcp`
拉网页、转 Markdown、截图	`https://browser.mcp.cloudflare.com/mcp`
快速洞察应用关键指标	`https://dex.mcp.cloudflare.com/mcp`
启动沙箱开发环境	`https://containers.mcp.cloudflare.com/mcp`

权限提醒：MCP 授权后 AI 就能对你的 Cloudflare 账户执行变更（建项目、删部署、改 DNS）。用完可以随时在 Cloudflare 后台 My Profile → API Tokens / OAuth Grants 里撤销授权。建议审查 AI 的部署指令，别让它删你现有的线上项目。

方式 C：AI 一键脚手架

如果你连网站都还没写，可以直接让 AI 建项目并部署：

Terminal

# 交互式：选框架 → 配好 → 询问是否部署
npm create cloudflare@latest -- --platform=pages

# 非交互式：直接指定一切
npm create cloudflare@latest -- --platform=pages ./my-site \
  --framework=vue \
  --deploy

Custom Domain

绑定自定义域名

.pages.dev 已经完全够用。但如果要给客户看、要做 SEO，换成自己的域名更专业。

前提：域名最好已经托管在 Cloudflare

如果你的域名已在 Cloudflare 的 DNS 里，接入就是全自动的。如果还在别家 registrar，两种做法：

方案 A：把域名接入 Cloudflare（推荐）

在 Cloudflare 控制台点 Add a domain，输入你的域名（如 example.com）
选择 Free 套餐
Cloudflare 扫描出你原来的 DNS 记录，确认无误后点击继续
Cloudflare 给你两个 nameserver，去原 registrar 把域名的 NS 改成这两个
等待 DNS 生效（通常几分钟到 48 小时）
生效后进 Pages 项目 → Custom domains → 添加域名，全部自动配置完成

额外好处：享受 Cloudflare 全套防护、缓存、分析，且不受下节提到的 Workers 域名限制。

方案 B：DNS 留在原服务商

先在 Pages 项目里添加域名（先做这步，Cloudflare 需要先验证归属）
Cloudflare 会给你一条 CNAME 记录
去 DNS 服务商把 www 或子域名指向 你的项目名.pages.dev

DNS 记录示例

# 在你的 DNS 服务商添加
www    CNAME    你的项目名.pages.dev

限制：裸域名（example.com，不带任何前缀）在非 Cloudflare DNS 下需要 A 记录指向 IP，目前不支持。改用 www.example.com 或任意子域名都可以。

✓

SSL 证书 完全自动，签发通常在 15 分钟内完成，不需要手动配置任何东西。

Important

Pages 与 Workers 的关系（重要）

这一节值得读，因为 Cloudflare 官方在 2026 年调整了产品定位，可能影响你的长期选择。

官方文档现在的原话："Workers supports most Pages use cases and offers a broader feature set. It is Cloudflare's primary platform for building applications. Start new projects with Workers."（Workers 支持 Pages 的绝大多数使用场景，且功能更广。Workers 是 Cloudflare 的主要应用平台，新项目请从 Workers 开始。）

Workers 官方主推

静态资源 + API + SSR 全一体
Durable Objects、Queues、Cron
原生 Rollback、渐进式发布
更完整的日志与可观测性
框架适配器更新最快

自定义域名的 NS 必须由 Cloudflare 托管
没有直观的"拖文件夹"控制台

给你的实际建议

纯静态展示站 / 个人博客 / 作品集 → Pages 完全够用，别折腾。拖拽 3 分钟上线。
要跑边缘函数、SSR、写 API → 直接考虑 Workers，别从 Pages 起步。
已经在 Pages 上跑着的项目 → 不用急着迁，功能都能用。等有 Workers 独有能力（Durable Objects、Cron）再迁。
迁移命令很简单：npx wrangler pages deploy → npx wrangler deploy，主要工作量在改配置（pages_build_output_dir → assets.directory）。

Next.js 用户注意：官方预设里还写着 npx next-on-pages@1，但这个方案基本已停止维护 —— 只支持 Edge Runtime，不能用 Node.js 内置模块（fs、crypto 等），ISR 也受限，社区 issue 积压很多。官方现在主推 OpenNext。三条路：① 纯静态导出（output: 'export'，Pages 直接支持，最省事）② next-on-pages（旧，别碰）③ OpenNext（新，推荐）。

这是官方文档更新滞后于弃用公告的典型例子 —— 看到官方文档里过时的方案，务必再查一下最新公告。

Troubleshooting

常见问题排查

按症状查，大部分问题都能在这里解决。

部署完了，访问显示 404

最常见的三个原因：

多套了一层目录。访问 https://xxx.pages.dev 显示找不到文件，去构建日志看它打包了哪些路径。检查是不是传了父目录。
没有 index.html。Pages 靠 index.html 作为根路径入口，没有它就 404。
单页应用（SPA）刷新 404。你的项目只有一个 index.html，路由靠前端 JS 处理。需要额外放一个 404.html（内容可以是跳回首页的脚本），或在 Workers 上设 not_found_handling: "single-page-application"。

图片、CSS、JS 加载不出来，页面一片空白

基本都是路径写成了绝对路径。检查代码里有没有：

src="/assets/app.js" —— 根路径开头的，在子路径下会 404
background-image: url("C:\\Users\\你的名字\\...") —— 本地绝对路径

改成相对路径：src="./assets/app.js"。用浏览器开发者工具（F12 → Network）能看到具体哪个文件 404。

Git 部署时构建失败

点开构建日志看第一处报错。常见方向：

Node 版本不匹配 → 在构建配置的环境变量里加 NODE_VERSION = 22
依赖没装全 → 构建命令填 npm install && npm run build
构建输出目录填错 → 这是最高频的原因，对照前面的表格核对你的框架该填什么
锁文件冲突 → 本地删掉 package-lock.json / pnpm-lock.yaml 重新提交，让云端用包管理器默认版本解析
环境变量缺失 → 在 Environment variables 里补上，注意要分别配置 Production 和 Preview

拖拽时文件标红，上传失败

单个文件超过 25 MiB。处理办法：

大图片转成 WebP / AVIF，通常能压到原来的 1/5
大视频别放静态站，走 R2 对象存储再引用
加 .assetsignore（Workers）或调整构建配置排除源文件，只传产物

注意：单个文件上传失败后无法单独替换，只能把整个项目重新传一遍。传之前先本地检查文件大小能省很多事。

项目名 / 域名能改吗

项目名：不能直接改。要换名字只能新建项目再重新部署。
域名：可以改。Custom domains 里可以增删，自定义域名加好后不需要重新构建。

另外，直接上传（Direct Upload）的项目控制台里没有生产分支配置项，想改只能调 API：

Terminal

curl --request PATCH "https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"production_branch": "main"}'

拖拽部署的项目，之后还能改成 Git 自动部署吗

不能。用直接上传（Direct Upload）创建的项目无法再连接 Git 仓库，只能新建一个走 Git 集成的项目。

所以如果你确定要做长期项目，一开始就选 Git 集成，别用拖拽。反过来，如果只是试试看，拖拽完全没问题。

免费额度具体是多少

项目	免费额度
托管带宽	无硬性限制（Pages 不按流量计费）
构建次数	每月 500 次（远超日常需求）
构建时长	每次 20 分钟上限
站点数量	无限
静态请求	Workers 静态资源请求免费
Pages Functions	每日 100,000 次请求免费

对绝大多数个人项目来说，这个额度等于"随便用，不会超"。

我的项目有后端接口 / 需要数据库怎么办

Pages 的强项是静态托管。动态需求有几种路径：

Pages Functions（functions/ 目录）：边缘函数，跑在 Workers 运行时上，能连 KV / D1 / R2。注意控制台拖拽不支持编译这个目录，必须用 Wrangler 上传。
纯 Workers：如果需求是复杂路由、WebSocket、定时任务、邮件处理，直接用 Workers，别硬套 Pages。
HonoX：想在 Workers 上保留文件式路由体验，这是官方推荐的框架。

判断很简单：纯展示 → Pages；需要算逻辑 → Workers。

AI 部署时它一直报错 / 连不上

确认 MCP 配置里 URL 完整（https://mcp.cloudflare.com/mcp），少了结尾的 /mcp 会连不上
某些客户端强制走 SSE 传输，会失败 —— 切到 Streamable HTTP 或自动传输检测
授权要重做：退出 Cloudflare 登录态，清掉客户端的 OAuth 缓存后重新连
网络问题：MCP Server 在海外，如果网络不通可以先跑拖拽或 CLI 路线
如果连了多个 MCP Server，AI 可能调错了工具，明确告诉它"用 cloudflare-api 这个 server"

接下来做什么

Step 1

现在就上线

按路线一拖拽，三分钟后你会拿到一个 .pages.dev 地址。

Step 2

接上 AI

配好 MCP，以后让 AI 帮你改站点、查部署、看日志。

Step 3

变成长期项目

迁移到 Git 集成，之后每次 push 自动部署，还有预览环境。