如何把自己的项目部署到 Cloudflare

先选择适合你的部署方式

如果项目会长期更新，优先选择 GitHub 集成。直接上传更适合一次性页面或你明确希望手动控制发布时间的项目。

部署前准备

1. 注册并登录一个 Cloudflare 账号。
2. 本机安装当前 Node.js LTS 版本，并确认 node -v 和 npm -v 可以运行。
3. 确认项目最终输出目录。纯静态网页可能是 public，Vite 默认是 dist，Create React App 通常是 build。
4. 确保输出目录根部包含 index.html。

Vite 项目先执行构建

npm install
npm run build

# Vite 默认会生成 dist 目录
ls dist

方式一：直接部署静态网页

这种方式使用 Cloudflare 官方命令行工具 Wrangler，把一个已经准备好的静态目录上传到 Pages。

1. 在项目中安装 Wrangler

npm install -D wrangler

2. 登录 Cloudflare

npx wrangler login

浏览器会打开 Cloudflare 授权页面。确认授权后回到终端。

3. 创建 Pages 项目

npx wrangler pages project create my-project

把 my-project 换成你的项目名。项目名会用于生成默认的 pages.dev 地址。

4. 上传构建产物

Vite 项目通常上传 dist：

npx wrangler pages deploy dist --project-name=my-project

如果是没有构建步骤的纯静态网页，并且全部文件都放在 public 目录：

npx wrangler pages deploy public --project-name=my-project

部署完成后，终端会返回一个可访问地址。以后更新代码时，重新构建并再次执行同一条部署命令。

直接上传的是“最终产物目录”，不是整个源代码目录。不要把 src、配置文件和未构建的 React 源码直接上传。

方式二：连接 GitHub 自动部署

GitHub 集成会在你推送代码后自动拉取仓库、安装依赖、执行构建并发布。分支提交还可以生成独立的预览地址。

1. 把项目推送到 GitHub

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/your-name/your-project.git
git push -u origin main

2. 在 Cloudflare 连接仓库

1. 打开 Cloudflare Dashboard，进入 Workers & Pages。
2. 选择 Create application，然后选择 Pages 和 Connect to Git。
3. 授权 Cloudflare 访问 GitHub，并选择要部署的仓库。
4. 选择生产分支，通常是 main。

3. 填写构建配置

如果项目位于仓库子目录，还需要设置 Root directory。需要在构建时使用的公开配置，可以放在 Environment variables 中；密钥不要写进前端代码。

4. 保存并部署

点击保存并部署。第一次构建完成后，每次向生产分支推送代码都会触发新的生产部署；其他分支和 Pull Request 通常会生成预览部署。

绑定自己的域名

1. 进入对应的 Pages 项目。
2. 打开 Custom domains。
3. 选择添加域名，输入根域名或子域名。
4. 按照页面提示确认 DNS 配置，等待证书签发完成。

域名已经托管在同一个 Cloudflare 账号时，DNS 配置通常可以自动完成。域名在其他 DNS 服务商时，需要按提示添加 CNAME 等记录。

常见问题

访问后显示 404

检查部署的输出目录根部是否存在 index.html。最常见的错误是上传了项目根目录，而不是 dist 或 public。

页面打开但样式和图片丢失

检查 HTML 中的资源路径。站点部署在域名根路径时，优先使用 /assets/... 或由构建工具生成的路径，不要引用本机文件路径。

React Router 刷新后 404

在静态输出目录中增加 _redirects 文件：

/* /index.html 200

GitHub 自动构建失败

先在本地重新执行 npm install 和 npm run build。然后检查 Cloudflare 的构建日志、Node.js 版本、环境变量、根目录和输出目录是否与项目一致。

官方参考

• Cloudflare Pages Direct Upload
• Cloudflare Pages Git integration
• Cloudflare Pages Custom domains