Cloudflare Pages 完整部署教程（从零到上线）

前置准备

1. 安装 Node.js

# 检查是否已安装
node --version
npm --version

# 如果没有安装，去 https://nodejs.org 下载 LTS 版本

2. 注册 Cloudflare 账号

访问 Cloudflare官网
使用邮箱注册并验证

3. 安装 Wrangler CLI

# 全局安装（推荐）
npm install -g wrangler

# 或者使用 npx（不安装）
npx wrangler --version

项目构建

准备你的前端项目

示例 1：纯静态 HTML/CSS/JS

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <title>我的网站</title>
    <style>
        body { font-family: Arial; text-align: center; padding: 50px; }
    </style>
</head>
<body>
    <h1>Hello Cloudflare Pages!</h1>
    <p>部署成功 🎉</p>
</body>
</html>

示例 2：React 项目

# 创建 React 项目
npm create vite@latest my-app -- --template react
cd my-app
npm install

# 构建项目
npm run build
# 构建产物在 dist 文件夹

示例 3：Vue 项目

# 创建 Vue 项目
npm create vue@latest my-app
cd my-app
npm install

# 构建项目
npm run build
# 构建产物在 dist 文件夹

验证构建产物

# 检查 dist 文件夹是否存在
ls -la dist/
# 应该包含 index.html 和其他静态文件

部署步骤

方法一：使用 Wrangler CLI（推荐）

步骤 1：登录 Cloudflare

# 全局安装后直接使用
wrangler login

# 或使用 npx
npx wrangler login

预期结果：

自动打开浏览器
点击 “Allow” 授权
终端显示 ✅ Successfully logged in

步骤 2：部署到 Cloudflare Pages

# 基础部署（预览环境）
wrangler pages deploy ./dist --project-name "my-first-site"

# 部署到生产环境
wrangler pages deploy ./dist --project-name "my-first-site" --branch main

# 指定自定义预览名称
wrangler pages deploy ./dist --project-name "my-first-site" --branch preview

步骤 3：查看部署结果

# 部署成功会显示
✨ Success! Uploaded 15 files and assets
🌎 Project name: my-first-site
🔗 Preview URL: https://abc123.my-first-site.pages.dev
⚡ Production URL: https://my-first-site.pages.dev

方法二：使用 Git 连接（适合团队协作）

步骤 1：推送代码到 GitHub

git init
git add .
git commit -m "首次提交"
git branch -M main
git remote add origin https://github.com/你的用户名/项目名.git
git push -u origin main

步骤 2：在 Cloudflare Dashboard 配置

登录 Cloudflare Dashboard
点击左侧 Pages
点击 Create a project → Connect to Git
选择 GitHub，授权并选择仓库
配置构建设置：
- Build command: npm run build
- Build output directory: dist
点击 Save and Deploy

高级配置

1. 自定义域名

# 在 Cloudflare Dashboard 中配置
# Pages → 你的项目 → Custom domains → Set up a custom domain
# 输入你的域名（如：www.example.com）

2. 环境变量配置

# 部署时指定环境变量
wrangler pages deploy ./dist \
  --project-name "my-site" \
  --env production \
  --var API_URL:https://api.example.com \
  --var DEBUG:false

或创建 .env.production 文件：

VITE_API_URL=https://api.example.com
VITE_APP_TITLE=我的网站

3. 重定向和 Rewrite 规则

创建 _redirects 文件在 dist 目录：

# dist/_redirects
/*    /index.html    200

# 重定向
/old-path  /new-path  301

4. 缓存配置

创建 _headers 文件：

# dist/_headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

*.css
  Cache-Control: max-age=31536000

*.js
  Cache-Control: max-age=31536000

5. 自动部署脚本

创建 deploy.sh：

#!/bin/bash

# 构建项目
echo "📦 构建项目..."
npm run build

# 部署到 Cloudflare
echo "🚀 部署到 Cloudflare Pages..."
wrangler pages deploy ./dist --project-name "my-site" --branch main

# 打开预览 URL
echo "🌐 打开网站..."
open https://my-site.pages.dev

# 添加执行权限
chmod +x deploy.sh

# 运行
./deploy.sh

6. GitHub Actions 自动部署

创建 .github/workflows/deploy.yml：

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm install
        
      - name: Build project
        run: npm run build
        
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-site
          directory: dist

常见问题

Q1: 登录失败怎么办？

# 清除缓存重新登录
rm -rf ~/.wrangler
wrangler login

# 或使用 API Token
wrangler login --no-browser

Q2: 部署时显示 “Project name already exists”

# 项目名需要全局唯一，换个名字
wrangler pages deploy ./dist --project-name "your-unique-name-2024"

Q3: 部署后页面显示 404

# 检查是否有 index.html
ls dist/index.html

# 添加 _redirects 文件处理 SPA 路由
echo "/* /index.html 200" > dist/_redirects

Q4: 如何删除/更新已部署的项目？

# 更新：直接重新部署即可（会覆盖）
wrangler pages deploy ./dist --project-name "my-site"

# 删除：需要在 Dashboard 操作
# Pages → 项目 → Settings → Delete project

Q5: 部署速度慢怎么办？

# 使用更快的上传方式
wrangler pages deploy ./dist \
  --project-name "my-site" \
  --upload-concurrency 10  # 增加并发上传数

Q6: 如何查看部署历史？

# CLI 查看
wrangler pages deployment list --project-name "my-site"

# 或访问 Dashboard
# https://dash.cloudflare.com/?to=/:account/pages/view/my-site

完整示例：部署 React 应用

# 1. 创建项目
npm create vite@latest react-app -- --template react
cd react-app

# 2. 安装依赖
npm install

# 3. 本地测试
npm run dev

# 4. 构建项目
npm run build

# 5. 配置重定向（SPA）
echo "/* /index.html 200" > dist/_redirects

# 6. 登录 Cloudflare
wrangler login

# 7. 部署
wrangler pages deploy ./dist --project-name "my-react-app" --branch main

# 8. 查看结果
# 访问: https://my-react-app.pages.dev

快速参考卡片

# 常用命令速查
wrangler login                                    # 登录
wrangler pages deploy ./dist --project-name "x"  # 部署预览
wrangler pages deploy ./dist --project-name "x" --branch main  # 部署生产
wrangler pages project list                       # 查看所有项目
wrangler pages deployment list --project-name "x" # 查看部署历史
wrangler pages project delete --project-name "x"  # 删除项目

# 部署后访问
# 预览: https://随机字符串.项目名.pages.dev
# 生产: https://项目名.pages.dev