cloudflare-deploy

Cloudflare 部署

使用 cf 执行 Cloudflare 操作。使用下方的决策树选择产品，然后阅读其运行时/API 参考和最新的 cf CLI 指南。

前置条件

• 需要 Node.js 24+ 和 pnpm。安装 npm 包 cf，而不是 @cloudflare/cf。
• 将 cf 保留在项目的 devDependencies 中，并提交锁文件。已验证的示例使用 [email protected] 和 @cloudflare/vite-plugin@beta；升级时请重新检查帮助信息和类型。
• Workers 使用 cloudflare.config.ts。对于现有的 Wrangler 项目，先运行 cf migrate --dry-run，再运行 cf migrate，并在执行项目命令前处理后续事项。自动配置不会导入旧的绑定。

身份验证（部署前必需）

发布或修改账户资源前，请先验证身份验证状态：

pnpm exec cf auth whoami

请参阅身份验证。在本地使用 pnpm exec cf auth login；cf 使用自己的登录凭据。在 CI 中设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID。部署试运行不需要凭据。

运行命令前先查找命令

pnpm exec cf cli search "create a D1 database"
pnpm exec cf schema d1 create
pnpm exec cf d1 create --help

搜索查询中只描述操作和资源类型。将名称和 ID 传给查找到的命令，而不是传给搜索。API 命令会将 JSON 输出到 stdout，将进度信息输出到 stderr。资源命令通常使用 ID 和远程数据；请检查是否支持 --local，不要照搬 Wrangler 的 --remote、--env、--json 或 --yes 标志。

何时阅读 references/

当前的 CLI、迁移、配置和构建指南位于 references/cf/。产品参考资料保留了 SDK 和运行时相关知识；标记为 legacy 的文件仅保留旧版 CLI/配置示例，供迁移时参考。不要执行其中的 Wrangler 示例，也不要据此生成新的 Wrangler 配置。请使用 cf 搜索/schema 和类型化绑定来实现预期操作。

经验法则：

• 选择产品？使用下方的决策树，然后加载 references/<picked-product>/
• 编写 cloudflare.config.ts？请先阅读配置。
• 设置 CI/CD？请阅读 GitHub Actions。
• 部署失败？请阅读 cf 常见问题，然后阅读相应产品的运行时常见问题。
• 下方的最简示例涵盖 Workers + KV + secret——除此之外的内容，请查阅相应参考资料

最简 Worker 示例（可直接复制粘贴的起步模板）

从此 Worker、一个 KV 绑定和一个密钥开始。进行类型检查前，请按照配置参考设置 TypeScript：

// cloudflare.config.ts
import { bindings, defineConfig } from "cf/config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({
  worker: {
    name: "my-worker",
    entrypoint,
    compatibilityDate: "2026-09-30", // Today's date for a new Worker
    observability: { enabled: true },
    env: {
      CACHE: bindings.kv({ id: "REPLACE_WITH_KV_ID" }),
      API_SECRET: bindings.secret(),
    },
  },
});

// vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [cloudflare()] });

// src/index.ts
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const hit = await env.CACHE.get("greeting");
    return new Response(hit ?? "hello");
  }
} satisfies ExportedHandler<Env>;

初始化命令：

pnpm add -D cf @cloudflare/vite-plugin@beta vite typescript
pnpm exec cf kv namespaces create --title CACHE # Copy the returned ID into config
pnpm exec cf workers types                      # Generates .cloudflare/types/index.d.ts
pnpm exec cf dev                                # Vite reports the local URL
pnpm exec cf deploy --dry-run --secrets-file .env.production
pnpm exec cf deploy --secrets-file .env.production

部署时，将 API_SECRET 放入被忽略的 .env.production，本地开发时放入 .dev.vars。声明 bindings.secret() 会使该值成为部署验证时的必填项；CLI 进程中的 dotenvx 值不会自动成为 Worker 密钥。将 .cloudflare/types 添加到 tsconfig.json；完整的 TypeScript 设置请参阅配置参考。请谨慎更改现有 Worker 的兼容日期。

已验证的 cf beta 尚未实现实时日志流和旧版 Pages 资源部署，即使命令出现在搜索结果或帮助信息中也是如此。请使用控制面板中的 Workers Logs 查看日志；新 Web 项目请使用 Workers 静态资源。对于旧版 Pages 项目，请确保现有部署正常运行，同时规划迁移；不要臆造 cf pages deploy 的替代命令。请参阅限制。

对于 Pages / D1 / Durable Objects / 多环境 / CI，请查阅 references/。

快速决策树

“我需要运行代码”

Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → workers/ (framework) + static-assets/
├─ Maintain or migrate an existing Pages app → pages/ (legacy reference)
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/

“我需要存储数据”

Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/

“我需要使用 AI/ML”

Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/

“我需要网络/连接能力”

Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/

“我需要安全功能”

Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)

“我需要媒体/内容”

Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/

“我需要基础设施即代码”

Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)

产品索引

计算与运行时

产品	参考
Workers	references/workers/
Pages	references/pages/
Pages Functions	references/pages-functions/
Durable Objects	references/durable-objects/
Workflows	references/workflows/
Containers	references/containers/
Workers for Platforms	references/workers-for-platforms/
Cron Triggers	references/cron-triggers/
Tail Workers	references/tail-workers/
Snippets	references/snippets/
Smart Placement	references/smart-placement/

存储与数据

产品	参考
KV	references/kv/
D1	references/d1/
R2	references/r2/
Queues	references/queues/
Hyperdrive	references/hyperdrive/
DO Storage	references/do-storage/
Secrets Store	references/secrets-store/
Pipelines	references/pipelines/
R2 Data Catalog	references/r2-data-catalog/
R2 SQL	references/r2-sql/

AI 与机器学习

产品	参考
Workers AI	references/workers-ai/
Vectorize	references/vectorize/
Agents SDK	references/agents-sdk/
AI Gateway	references/ai-gateway/
AI Search	references/ai-search/

网络与连接

产品	参考
Tunnel	references/tunnel/
Spectrum	references/spectrum/
TURN	references/turn/
Network Interconnect	references/network-interconnect/
Argo Smart Routing	references/argo-smart-routing/
Workers VPC	references/workers-vpc/

安全

产品	参考
WAF	references/waf/
DDoS Protection	references/ddos/
Bot Management	references/bot-management/
API Shield	references/api-shield/
Turnstile	references/turnstile/

媒体与内容

产品	参考
Images	references/images/
Stream	references/stream/
Browser Rendering	references/browser-rendering/
Zaraz	references/zaraz/

实时通信

产品	参考
RealtimeKit	references/realtimekit/
Realtime SFU	references/realtime-sfu/

开发者工具

产品	参考
cf CLI	references/cf/
Miniflare	references/miniflare/
C3	references/c3/
Observability	references/observability/
Analytics Engine	references/analytics-engine/
Web Analytics	references/web-analytics/
Sandbox	references/sandbox/
Workerd	references/workerd/
Workers Playground	references/workers-playground/

基础设施即代码

产品	参考
Pulumi	references/pulumi/
Terraform	references/terraform/
API	references/api/

其他服务

产品	参考
Email Routing	references/email-routing/
Email Workers	references/email-workers/
Static Assets	references/static-assets/
Bindings	references/bindings/
Cache Reserve	references/cache-reserve/

故障排查

提升网络访问权限

如果部署因网络问题（超时、DNS 错误、连接重置）而失败，请使用提升的权限重新运行部署（使用 sandbox_permissions=require_escalated）。当沙盒网络阻止出站请求时，部署需要提升网络访问权限。

向用户提供的示例说明：

The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?