# Cloudflare 页面技能 **Cloudflare Pages** 是一个 JAMstack 平台，用于将全栈应用程序部署到 Cloudflare 的全球网络。它将静态站点托管与无服务器页面功能、自动 Git 部署以及与 Cloudflare 生态系统（Workers、KV、R2、D1、Durable Objects）的本机集成相结合。 **关键价值主张**：以零配置、自动预览部署、无限带宽以及无缝访问 Cloudflare 边缘计算和存储服务的方式部署静态站点和全栈应用程序。 ## 何时使用此技能 * 部署静态站点或 JAMstack 应用程序 * 使用无服务器功能构建全栈应用程序 * 使用绑定配置页面功能（KV、R2、D1） * 通过预览部署设置基于 Git 的 CI/CD * 配置标头、重定向和路由 * 解决构建或部署问题 * 从其他托管平台迁移到 Pages ## 何时不使用此技能 * 仅适用于 Cloudflare Workers（使用工人技能） * 适用于一般 Cloudflare CDN/DNS 配置 * 对于非 Web 应用程序或没有 UI 的 API * 适用于基于容器的部署（Pages 是无服务器的） ** ** ## 核心概念 ### 架构概述 ┌────────────────────────────────────────────────────────────────┐ │ Cloudflare 页面 │ │ 全球边缘网络（300+ PoP） │ └────────────────────────────────────────────────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────────┐ ┐────────────────┐ ┌──────────────┐ │ 静态资源 │ │ 页面函数 │ │ 绑定 │ ├────────────────┤ ├────────────────┤ ├────────────────┤ │ • HTML/CSS/JS │ │ • /functions/ │ │ • KV │ │ • 图像 │ │ • 中间件 │ │ • R2 │ │ • _headers │ │ • 路由 │ │ • D1 │ │ • _redirects │ │ • TypeScript │ │ • DO │ │ • _routes.json│ │ • Workers API │ │ • 队列 │ └────────────────┘ └────────────────┘ │ • 人工智能 │ │ │ └──────────────┘ └──────────────────────┼──────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ ▼ ▼ ▼ ┌────────────────┐ ┐────────────────┐ ┌──────────────┐ │ 部署 │ │ 域 │ │ 构建 │ ├────────────────┤ ├────────────────┤ ├────────────────┤ │ • Git (GH/GL) │ │ • 自定义 │ │ • 最多 20 分钟 │ │ • 直接 │ │ • *.pages.dev │ │ • 500/月免费 │ │ • Wrangler │ │ • 预览 URL │ │ • 环境变量 │ │ • API │ │ │ │ • 预设 │ └────────────────┘ └────────────────┘ └────────────────┘ ### 平台限制资源 |免费|专业|业务 |企业 ---|---|---|---|--- 构建/月 | 500 | 500 5,000 | 20,000 |无限自定义域 | 100 | 100 250 | 250 500 | 500 500 每个站点的文件 | 20,000 | 20,000 | 20,000 | 20,000 文件大小 | 25 MB | 25 MB | 25 MB | 25MB 预览部署 |无限|无限|无限|无限构建超时 | 20 分钟 | 20 分钟 | 20 分钟 | 20分钟 ### 配置限制配置 |限制 ---|--- 标题规则 |最多 100 个静态重定向 |最多 2,000 动态重定向 |最多 100 个重定向行长度| 1,000 个字符标题行长度| 2,000 个字符每个帐户的项目 | 100（软） ** ** ## 快速入门 ### 使用 Git 集成进行部署 # 1. 在 Cloudflare Dashboard 中连接存储库 # Workers & Pages > 创建应用程序 > 连接到 Git # 2. 配置构建设置 # - 生产分支：main # - 构建命令：npm run build # - 构建输出：dist # 3. 推送部署 git推送原点主要 ### 使用 Wrangler CLI 进行部署 # 安装牧马人 npm install -g 牧马人 # 登录 Cloudflare 牧马人登录 # 创建一个新项目 npx 牧马人页面项目创建我的网站 # 部署到生产环境 npx 牧马人页面部署 ./dist # 部署预览 npx Wrangler 页面部署 ./dist --branch=staging ### 通过仪表板部署 1. 转到 **Workers & Pages** > **创建应用程序** 2. 单击页面下的**开始** 3. 拖放构建文件夹或 zip 文件 4. 输入项目名称并部署 ** ** ## 构建配置 ### 框架预设 Cloudflare 提供了超过 31 个框架的预设：框架|构建命令|输出目录 ---|---|--- **反应（Vite）** | `npm 运行构建` | `距离` **Next.js** | `npx @cloudflare/next-on-pages@1` | `.vercel/输出/静态` **天文** | `npm 运行构建` | `距离` **SvelteKit** | `npm 运行构建` | `.svelte-kit/cloudflare` **Nuxt** | `npm 运行构建` | `距离` **混音** | `npm 运行构建` | ‘公共’ **Vue（Vite）** | `npm 运行构建` | `距离` **角度** | `npm 运行构建` | `dist/<项目>` **盖茨比** | `盖茨比构建` | ‘公共’ **雨果** | `雨果` | ‘公共’ **多库龙** | `npm 运行构建` | `构建` **十一** | `npx @11ty/eleventy` | `_站点` ### 系统环境变量这些在构建期间自动注入：变量|描述 |示例 ---|---|--- `CF_PAGES` |页面上始终为“1” | `1` `CF_PAGES_COMMIT_SHA` | Git 提交哈希 | `a1b2c3d...` `CF_PAGES_BRANCH` |分公司名称 | `主要` `CF_PAGES_URL` |部署 URL | `https://abc.pages.dev` `CI` |永远“真实” | `真实` ### 自定义环境变量 # 通过仪表板设置：设置 > 环境变量 # 或者在 wrangler.toml 中 [变量] API_URL =“https://api.example.com” # 秘密（加密） # 设置方式：wrangler 页面秘密 put SECRET_NAME ### Monorepo 配置我的-monorepo/ ├── 应用程序/ │ └── web/ # 根目录：apps/web │ ├── src/ │ └── package.json └── 包/ 在构建设置中将**根目录**设置为“apps/web”。 ** ** ## 页面功能 ### 目录结构我的项目/ ├── 功能/ │ ├── _middleware.js # 全局中间件 │ ├── API/ │ │ ├── _middleware.js # API 特定的中间件 │ │ ├──index.js # GET /api │ │ ├── 用户/ │ │ │ ├──index.js # GET /api/users │ │ │ └── [id].js # GET /api/users/:id │ │ └── [[catchall]].js # 包罗万象 │ └── health.js # GET /health ├── 公开/ │ └──index.html └── package.json ### 基本功能 // 函数/api/hello.ts 导出 const onRequestGet: PagesFunction = async (context) => { 返回新的响应（JSON.stringify（{消息：“你好！”}），{ headers: { "Content-Type": "application/json" } }); }; // 处理多个方法导出 const onRequest: PagesFunction = async (context) => { const { 请求 } = 上下文； if (request.method === "POST") { const body =等待request.json(); 返回新的响应（JSON.stringify（body））； } return new Response("方法不允许", { status: 405 }); }; ### 动态路由 // 函数/用户/[id].ts 导出 const onRequestGet: PagesFunction = async (context) => { const { id } = context.params; // 字符串返回新的响应（`用户：$ {id}`）； }; // 函数/文件/[[路径]].ts（包罗万象）导出 const onRequestGet: PagesFunction = async (context) => { const { 路径 } = context.params; // 字符串[] return new Response(`路径: ${path.join("/")}`); }; ### 中间件 // 函数/_middleware.ts 导出 const onRequest: PagesFunction = async (context) => { // 在处理程序之前 console.log(`${context.request.method} ${context.request.url}`); 尝试{ // 调用下一个处理程序 const 响应 = 等待 context.next(); // 处理程序之后 - 修改响应 response.headers.set("X-Custom-Header", "value"); 返回响应； } 捕获（错误）{ 返回新的响应（“服务器错误”，{状态：500}）； } }; // 链接多个中间件导出 const onRequest = [errorHandler, auth, 日志记录]; 异步函数 errorHandler(context) { 尝试{ 返回等待上下文.next(); } 捕获（错误）{ 返回新的响应（err.message，{状态：500}）； } } 异步函数 auth(context) { const token = context.request.headers.get("授权"); 如果（！令牌）{ return new Response("未经授权", { status: 401 }); } 返回上下文.next(); } ### TypeScript 支持 // 函数/api/data.ts 接口环境{ KV：KV命名空间； DB：D1数据库；桶：R2桶； API_KEY：字符串； } 导出 const onRequestGet: PagesFunction = async (context) => { const { env, request, params, waitUntil, passThroughOnException } = context; // 访问绑定 const value = wait env.KV.get("key"); const result = wait env.DB.prepare("SELECT * FROM users").all(); return Response.json({ value, users: result.results }); }; ** ** ## 绑定 ### KV 命名空间 // 函数/api/kv.ts 接口环境{ MY_KV: KV命名空间； } 导出 const onRequest: PagesFunction = async ({ env }) => { // 写等待 env.MY_KV.put("键", "值"); 等待 env.MY_KV.put("json", JSON.stringify({ foo: "bar" })); 等待 env.MY_KV.put("即将到期", "数据", {expirationTtl: 3600 }); // 读取 const value = wait env.MY_KV.get("key"); const json =等待 env.MY_KV.get("json", { type: "json" }); // 列表 const list = wait env.MY_KV.list({ 前缀: "用户:" }); // 删除等待 env.MY_KV.delete("key"); 返回 Response.json({ 值, json }); }; # 本地开发 npx 牧马人页面 dev ./dist --kv=MY_KV ### R2 铲斗 // 函数/api/files.ts 接口环境{ 桶：R2桶； } 导出 const onRequest: PagesFunction = async ({ env, request }) => { const url = 新 URL(request.url); const key = url.pathname.slice(1); 开关（请求方法）{ 案例“放置”：等待 env.BUCKET.put(key, request.body, { httpMetadata: { contentType: request.headers.get("content-type") } }); 返回新的响应（“已上传”）；案例“获取”： const 对象 = 等待 env.BUCKET.get(key); if (!object) return new Response("未找到", { status: 404 }); 返回新的响应（对象.body，{ headers: { "Content-Type": object.httpMetadata?.contentType || “应用程序/八位字节流”} }); 案例“删除”：等待 env.BUCKET.delete(key); 返回新的响应（“已删除”）； } }; # 本地开发 npx 牧马人页面 dev ./dist --r2=BUCKET ### D1 数据库 // 函数/api/user.ts 接口环境{ DB：D1数据库； } 导出 const onRequestGet: PagesFunction = async ({ env }) => { const { 结果 } = 等待 env.DB .prepare("从用户中选择 * WHERE active = ?") .绑定(1) .all(); 返回 Response.json(结果); }; 导出 const onRequestPost: PagesFunction = async ({ env, request }) => { const { 姓名，电子邮件 } = wait request.json(); const 结果 = 等待 env.DB .prepare("插入用户（姓名、电子邮件）值 (?, ?)") .bind(姓名、电子邮件) .run(); 返回 Response.json({ id: result.meta.last_row_id }); }; # 本地开发 npx 牧马人页面 dev ./dist --d1=DB=<数据库 ID> ### 耐用的物体 // 函数/api/counter.ts 接口环境{ 计数器：DurableObject命名空间； } 导出 const onRequest: PagesFunction = async ({ env, request }) => { const id = env.COUNTER.idFromName("全局"); const 存根 = env.COUNTER.get(id); 返回存根.fetch(请求); }; # 本地开发（需要具有 DO 的 Worker） npx 牧马人页面 dev ./dist --do=COUNTER=CounterDO@counter-worker ### 服务绑定 // 函数/api/proxy.ts 接口环境{ AUTH_SERVICE：获取器； } 导出 const onRequest: PagesFunction = async ({ env, request }) => { // 调用另一个Worker 返回 env.AUTH_SERVICE.fetch(请求); }; ### 队列生产者 // 函数/api/jobs.ts 接口环境{ MY_QUEUE：队列； } 导出 const onRequestPost: PagesFunction = async ({ env, request }) => { const job = 等待 request.json(); 等待 env.MY_QUEUE.send({ 类型：“过程”，数据：工作 }); 返回 Response.json({ 排队: true }); }; ### 工人人工智能 // 函数/api/ai.ts 接口环境{ 人工智能：艾； } 导出 const onRequestPost: PagesFunction = async ({ env, request }) => { const { 提示 } = 等待 request.json(); const 响应 = 等待 env.AI.run("@cf/meta/llama-2-7b-chat-int8", { 消息：[{角色：“用户”，内容：提示}] }); 返回 Response.json(响应); }; ** ** ## 静态配置 ### 标头 (_headers) # 应用于所有路径 /* X 帧选项：拒绝 X-内容类型选项：nosniff 推荐人策略：跨源时严格源 # API CORS 标头 /API/* 访问控制允许来源：* 访问控制允许方法：GET、POST、PUT、DELETE 访问控制允许标头：内容类型 # 缓存静态资源 /资产/* 缓存控制：公共，最大年龄=31536000，不可变 # HTML 的安全标头 /*.html 内容安全策略：default-src 'self' X-XSS-保护：1；模式=块 # 删除标头（前缀为 !） /公共/* ！ X-机器人标签 **注意**：自定义标头不适用于页面函数响应。 ### 重定向 (_redirects) # 简单重定向（默认302） /主页/ # 永久重定向 /旧页 /新页 301 # 外部重定向 /推特 https://twitter.com/example # Splat（通配符） /blog/* https://blog.example.com/:splat # 占位符 /用户/：id /配置文件/：id 301 # 代理（200 状态，仅限相对 URL） /api/* /functions/api/:splat 200 # 强制尾部斜杠 /关于 /关于/ 301 **限制**：最多 2,000 个静态 + 100 个动态重定向。 ### 路线 (_routes.json) { “版本”：1， “包括”：[“/ api / *”，“/ auth / *”]， “排除”：[“/ api / health”，“/ static / *”] } * 控制哪些路径调用函数 * “排除”优先于“包含” * 不匹配的路径将作为静态资源 * 最多组合 100 条规则 ** ** ## 部署方法 ### Git 集成（推荐） **GitHub 设置**： 1. Workers & Pages > 创建应用程序 > 连接到 Git 2.选择GitHub并授权 3.选择存储库 4. 配置构建设置 5. 部署 **GitLab 设置**： * 需要维护者角色或更高级别 * 授予对帐户上所有存储库的访问权限 **分支配置**： * 生产分支：`main`（可配置） * 预览分支：所有非生产分支（可配置） * 自定义规则：包含/排除模式 ### 直接上传（牧马人） # 创建项目 npx Wrangler 页面项目创建我的应用程序 # 列出项目 npx 牧马人页面项目列表 # 部署生产 npx 牧马人页面部署 ./dist # 部署预览 npx 牧马人页面部署 ./dist --branch=feature-x # 列出部署 npx Wrangler 页面部署列表 --project-name=my-app ### API部署 # 通过API创建部署卷曲-X POST \ “https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments”\ -H“授权：不记名{api_token}”\ -F“清单=@manifest.json”\ -F“file1=@dist/index.html” ** ** ## 本地发展 ### Wrangler 开发服务器 # 基础开发 npx 牧马人页面 dev ./dist # 带绑定 npx 牧马人页面 dev ./dist \ --kv=MY_KV \ --r2=桶 \ --d1=DB=<数据库 ID> \ --端口=8788 # 实时重新加载（框架开发服务器） npx wrangler 页面开发 -- npm run dev # 代理到另一台服务器 npx 牧马人页面 dev --proxy=3000 ### wrangler.toml 配置名称 =“我的页面项目” page_build_output_dir =“./dist” # 兼容性兼容性_日期=“2024-01-01” Compatibility_flags = [“nodejs_compat”] # 环境变量 [变量] API_URL =“https://api.example.com” # KV绑定 [[kv_命名空间]] 绑定=“MY_KV” id =“abc123” # R2 绑定 [[r2_buckets]] 绑定=“桶” Bucket_name = “我的存储桶” # D1 绑定 [[d1_数据库]] 绑定=“DB” 数据库名称=“我的数据库” 数据库 ID =“xyz789” # 耐用的物体 [[durable_objects.绑定]] 名称=“计数器” 类名=“计数器” script_name = "柜台人员" # 服务绑定 [[服务]] 绑定=“验证” service =“auth-worker” ** ** ## 分支构建控制 ### 预览部署设置 > 构建和部署 > 配置预览部署选项： * **所有非生产分支** ：默认，部署所有内容 * **无** ：禁用预览版本 * **自定义分支**：选择性部署 ### 自定义分支规则 # 包含模式 feat/* # 匹配 feat/login、feat/dashboard release-* # 匹配release-1.0,release-2.0 # 排除模式 dependentabot/* # 跳过依赖更新 wip/* # 跳过正在进行的工作 # 顺序：首先排除评估，然后包括 ### 跳过构建添加提交消息： git commit -m“更新文档 [CI SKIP]” git commit -m“小修复[跳过 ci]” ** ** ## 回滚 ### 通过仪表板 1. 转到项目 > 部署 2.找到要回滚的部署 3. 单击三个点 > 回滚到此部署 ### 通过牧马人 # 列出部署 npx Wrangler 页面部署列表 --project-name=my-app # 回滚（重新部署之前的部署） # 注意：直接回滚命令不可用； # 重新部署特定提交或使用仪表板 ** ** ## 故障排除 ### 构建失败错误：构建命令失败 **解决方案**： 1. 检查构建日志中是否有特定错误 2. 验证构建命令和输出目录 3.本地测试：`npm run build` 4.检查Node.js版本兼容性 5.查看环境变量 ### 函数 500 错误错误：内部服务器错误 **解决方案**： 1. 检查仪表板中的功能日志 2. 验证绑定是否已配置 3. 使用“wrangler Pages dev”进行本地测试 4. 检查未处理的承诺拒绝 ### 静态资源 404 错误：找不到页面 **解决方案**： 1.验证构建输出目录是否正确 2. 检查 `_routes.json` 是否排除路径 3. 确认文件存在于构建输出中 4. 检查 `_redirects` 是否有冲突 ### 未找到绑定错误：无法读取未定义的属性 **解决方案**： 1. 验证仪表板中是否配置了绑定 2. 检查绑定名称与代码是否匹配 3. 对于本地开发，将绑定标志传递给 wrangler 4.验证wrangler.toml配置 ### 标头/重定向不起作用 **可能的原因**： 1. 文件位置不正确（必须位于构建输出中） 2. 文件中的语法错误 3. 对于函数响应，请使用代码 4. 超出限制（100 个标头，2100 个重定向） ** ** ## 最佳实践 ### 项目结构我的应用程序/ ├──functions/ # 服务器端代码 │ ├── _middleware.ts # 全局中间件 │ └── api/ # API 路由 ├── public/ # 静态资源（复制到dist） │ ├── _headers # 标头规则 │ ├── _redirects # 重定向规则 │ └── 机器人.txt ├── src/ # 源代码 ├── dist/ # 构建输出（gitignored） ├── wrangler.toml # 牧马人配置 └── package.json ### 安全建议 1.使用环境变量作为秘密 2. 为API正确实施CORS 3. 添加安全标头（CSP、X-Frame-Options） 4. 验证和清理用户输入 5. 使用仅 HTTPS 的自定义域 6. 检查函数权限和绑定 ### 性能提示 1. 使用 `_routes.json` 跳过静态路径的 Functions 2. 设置适当的 Cache-Control 标头 3.上传前优化图片 4. 对大型应用程序使用代码分割 5. 利用 Cloudflare 的全球 CDN ** ** ## 资源 ### 官方文档 * [页面文档]() * [功能指南]() * [框架指南]() * [平台限制]() ### 工具 * [Wrangler CLI]() * [C3（创建 Cloudflare）]() ### 相关服务 * [工人]() * [KV]() * [R2]() * [D1]() * [持久对象]() ### 社区 * [Discord]() * [社区论坛]() * [@CloudflareDev]() ** ** ## 版本历史 * **1.0.0** (2026-01-13): 初始技能发布 * 完整的Pages平台文档 * 静态站点和全栈部署指南 * 带有路由和中间件的页面功能 * 所有绑定（KV、R2、D1、DO、队列、AI） * 构建配置和框架预设 * 标头、重定向和路由配置 * Git集成和直接上传方法 * 与 Wrangler 一起进行本地开发 * 分支构建控制和回滚 * 故障排除指南

Cloudflare 页面

包含技能