Pages

Cloudflare Pages 是一个静态网站托管平台，支持自动构建和部署，与 GitHub、GitLab 深度集成。它提供无限带宽、全球 CDN 加速，非常适合托管静态网站、博客、文档站点等。

Pages 简介

什么是 Pages？

Pages 是 Cloudflare 提供的 JAMstack 平台，可以：

自动从 Git 仓库构建和部署网站
托管静态网站和单页应用（SPA）
集成 Cloudflare Workers 实现动态功能
提供预览部署，每个 PR 都有独立预览链接

Pages 的优势

免费无限带宽：与 Vercel、Netlify 相比，Pages 免费版提供无限带宽。

全球 CDN：网站自动部署到全球 300+ 边缘节点。

自动 HTTPS：免费 SSL 证书，自动续期。

预览部署：每个 Pull Request 都有独立的预览链接。

Workers 集成：可以添加 Functions 实现动态功能。

免费计划限制

资源	限制
并发构建	1 个
每月构建次数	500 次
自定义域名	100 个
文件数量	20,000 个
单文件大小	25MB
Functions 请求	10 万次/天

快速开始

方式一：连接 Git 仓库

登录 Cloudflare 控制台
进入 "Workers & Pages" → "Create application"
选择 "Pages" → "Connect to Git"
授权 GitHub 或 GitLab
选择要部署的仓库
配置构建设置
点击 "Save and Deploy"

方式二：直接上传

进入 "Workers & Pages" → "Create application"
选择 "Pages" → "Upload assets"
输入项目名称
拖拽或选择文件上传
点击 "Deploy site"

使用 Wrangler 部署

# 部署当前目录
npx wrangler pages deploy ./dist

# 指定项目名称
npx wrangler pages deploy ./dist --project-name=my-site

构建配置

框架预设

Pages 内置了常见框架的构建配置：

框架	构建命令	输出目录
Next.js (Static)	`npm run build`	`out`
React (Create React App)	`npm run build`	`build`
Vue.js	`npm run build`	`dist`
Angular	`npm run build`	`dist/browser`
Astro	`npm run build`	`dist`
Hugo	`hugo`	`public`
Jekyll	`jekyll build`	`_site`
Hexo	`hexo generate`	`public`

自定义构建

如果框架不在预设中，可以自定义：

Framework preset: None
Build command: npm run build
Build output directory: dist
Root directory: /

环境变量

在构建设置中添加环境变量：

Settings → Environment variables

可以设置：

Production 环境变量
Preview 环境变量

Functions

Pages 可以添加 Functions 来实现动态功能，Functions 本质上是 Workers。

创建 Function

在项目根目录创建 functions 目录：

project/
├── functions/
│   └── api/
│       └── hello.ts
├── dist/
└── ...

Function 示例

functions/api/hello.ts：

export async function onRequest(context) {
  const { request, env, params } = context;

  return new Response(JSON.stringify({
    message: 'Hello from Pages Functions!'
  }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

访问 https://your-site.pages.dev/api/hello 即可调用。

处理不同 HTTP 方法

export async function onRequestGet(context) {
  return new Response('GET request');
}

export async function onRequestPost(context) {
  const body = await context.request.json();
  return Response.json({ received: body });
}

使用环境变量

export async function onRequest(context) {
  const apiKey = context.env.API_KEY;
  return Response.json({ apiKey });
}

绑定 KV/R2/D1

在 Pages 设置中配置绑定：

Settings → Functions → KV namespace bindings
Settings → Functions → R2 bucket bindings
Settings → Functions → D1 database bindings

使用绑定：

export async function onRequest(context) {
  const value = await context.env.MY_KV.get('key');
  return Response.json({ value });
}

预览部署

自动预览

每次推送到非主分支或创建 PR 时，Pages 会自动创建预览部署：

https://<commit-hash>.<project>.pages.dev

预览设置

在项目设置中可以配置：

预览分支白名单
预览访问控制（密码保护）

自定义域名

添加域名

进入项目设置
选择 "Custom domains"
点击 "Set up a custom domain"
输入域名
按提示配置 DNS

DNS 配置

如果域名托管在 Cloudflare：

自动配置 CNAME 记录

如果域名托管在其他地方：

添加 CNAME 记录指向 <project>.pages.dev

子域名路由

可以配置不同子域名指向不同路径：

blog.example.com → /blog
docs.example.com → /docs

重定向与重写

_redirects 文件

在输出目录创建 _redirects 文件：

# 简单重定向
/old-page /new-page 301

# 代理（需要 Functions）
/api/* https://api.example.com/:splat 200

# SPA 路由回退
/* /index.html 200

_headers 文件

在输出目录创建 _headers 文件：

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

/assets/*
  Cache-Control: public, max-age=31536000

部署钩子

部署成功通知

可以配置部署成功后通知：

Slack
Discord
自定义 Webhook

部署触发

使用 Deploy Hook 触发部署：

curl -X POST "https://api.cloudflare.com/client/v4/pages/webhooks/deploy_hooks/<token>"

本地开发

安装 Wrangler

npm install -g wrangler

本地运行

# 运行静态文件服务
npx wrangler pages dev ./dist

# 带 Functions 开发
npx wrangler pages dev ./dist --compatibility-flag=nodejs_compat

绑定本地服务

npx wrangler pages dev ./dist --kv=MY_KV --r2=MY_BUCKET

实战示例

部署 React 应用

# 创建 React 应用
npx create-react-app my-app
cd my-app

# 构建
npm run build

# 部署
npx wrangler pages deploy build --project-name=my-react-app

部署 Vue 应用

# 创建 Vue 应用
npm create vue@latest my-vue-app
cd my-vue-app
npm install

# 构建
npm run build

# 部署
npx wrangler pages deploy dist --project-name=my-vue-app

部署静态博客（Hexo）

# 安装 Hexo
npm install -g hexo-cli
hexo init my-blog
cd my-blog
npm install

# 生成静态文件
hexo generate

# 部署
npx wrangler pages deploy public --project-name=my-blog

部署文档站点（Docusaurus）

# 创建 Docusaurus 项目
npx create-docusaurus@latest my-website classic
cd my-website

# 构建
npm run build

# 部署
npx wrangler pages deploy build --project-name=my-docs

CI/CD 集成

GitHub Actions

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - 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

常见问题

构建失败怎么办？

检查构建日志
确认构建命令和输出目录正确
检查 Node.js 版本是否匹配
确认依赖安装正确

SPA 路由 404 怎么办？

添加 _redirects 文件：

/* /index.html 200

如何配置 Node.js 版本？

在环境变量中设置：

NODE_VERSION=20

或在项目根目录创建 .nvmrc 文件：

参考链接

下一步

完成 Pages 学习后，接下来学习 R2 存储，了解如何使用对象存储服务。

Pages 简介​

什么是 Pages？​

Pages 的优势​

免费计划限制​

快速开始​

方式一：连接 Git 仓库​

方式二：直接上传​

使用 Wrangler 部署​

构建配置​

框架预设​

自定义构建​

环境变量​

Functions​

创建 Function​

Function 示例​

处理不同 HTTP 方法​

使用环境变量​

绑定 KV/R2/D1​

预览部署​

自动预览​

预览设置​

自定义域名​

添加域名​

DNS 配置​

子域名路由​

重定向与重写​

_redirects 文件​

_headers 文件​

部署钩子​

部署成功通知​

部署触发​

本地开发​

安装 Wrangler​

本地运行​

绑定本地服务​

实战示例​

部署 React 应用​

部署 Vue 应用​

部署静态博客（Hexo）​

部署文档站点（Docusaurus）​

CI/CD 集成​

GitHub Actions​

常见问题​

构建失败怎么办？​

SPA 路由 404 怎么办？​

如何配置 Node.js 版本？​

参考链接​

下一步​