企业官网建设流程全解析

Cloudflare C3（create-cloudflare）CLI 完全参考：命令调用、核心参数与 CI/CD 实战指南

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本指南以skills/.curated/cloudflare-deploy技能仓库中的 C3 CLI Reference 为骨架，完整讲解 Cloudflare 官方脚手架 C3（create-cloudflare）的调用方式、全部命令行标志、环境变量、退出码与实战示例，并结合同目录下的 README、configuration.md、patterns.md、gotchas.md 及仓库中的 SKILL.md 展开源码级佐证。读完本文，你将能熟练使用 C3 以交互式或全非交互方式创建 Workers 与 Pages 项目、在 CI/CD 中无阻塞地完成脚手架初始化、理解 C3 生成的工程结构与绑定占位符，并快速定位部署失败原因。

C3 是什么

C3（create-cloudflare）是 Cloudflare 官方的项目脚手架 CLI，用于一键创建 Workers 与 Pages 项目，内置模板、TypeScript 支持与即时部署能力。它由npm create cloudflare@latest驱动，本质上是对模板系统的封装：通过--type指定应用形态、--framework选择 Web 框架、--platform决定目标平台（Workers 或 Pages），最终生成一个可直接npm run dev本地调试、npm run deploy发布上线的完整工程。

在skills/.curated/cloudflare-deploy这一技能仓库中，C3 属于「开发者工具」产品线，与 Wrangler、Miniflare、Observability 并列（见 SKILL.md）。它的定位是项目初始化阶段工具：创建工程、选择平台与框架、生成配置文件；而初始化之后的绑定管理、本地开发、发布部署则交由 Wrangler CLI 完成。二者职责互补：C3 负责「脚手架」，Wrangler 负责「日常运维」。

命令调用方式（Invocation）

C3 支持三种主流的 Node.js 包管理器调用方式，命令形态完全一致，仅在使用 npm 与 pnpm 时需要在参数前额外加--分隔符，让包管理器把后续参数透传给 C3：

npm create cloudflare@latest [name] [-- flags] # NPM requires -- yarn create cloudflare [name] [flags] pnpm create cloudflare@latest [name] [-- flags]

• [name]是可选的项目目录名。省略时进入交互式向导（Interactive Flow）；传入.则表示在当前目录就地初始化（常用于把已有项目转换为 Cloudflare 工程）。
• [-- flags]是需要透传的 CLI 参数。npm 与 pnpm 必须用--分隔，否则参数会被 npm/pnpm 自身消费；yarn 直接拼接即可。
• 使用@latest标签始终拉取最新版本；不指定版本号时 npm 会使用缓存或本地的版本。

交互式模式下，C3 会按固定顺序依次提问：项目名（name，默认当前目录，使用.）→ 应用类型（hello-world、web-app、demo、pre-existing、remote-template）→ 平台（仅 web-app 才询问，workers默认 /pages）→ 框架（web-app 时：next、remix、astro、react-router、solid、svelte 等）→ 是否使用 TypeScript（推荐 yes）→ 是否初始化 Git（yes/no）→ 是否立即部署（yes/no，需要先wrangler login）。首次使用建议直接不带任何参数运行，让交互向导带你走完整个流程，详见 README 的 Interactive Flow 小节。

核心标志（Core Flags）

核心标志决定「创建什么样的项目」。完整参数表来自 api.md：

--type：五种应用类型

• hello-world：最小的可运行模板，用于 API、WebSocket、Cron 定时任务等单文件 Worker。结合--lang可选 TypeScript、JavaScript 或 Python。
• web-app：全栈 Web 应用，必须配合--framework指定框架，并通过--platform选择部署到 Workers 还是 Pages。
• demo：演示类项目，配合--category筛选演示主题。
• pre-existing：把已有的 Worker 脚本转换为 Cloudflare 工程，配合--existing-script指定脚本路径。
• remote-template：使用远程模板，配合--template指定 GitHub 仓库或本地路径。

--platform：Workers 还是 Pages

关键提醒（Critical）：Pages 项目必须显式加--platform=pages，否则 C3 一律默认使用 Workers。这一点在 README 的平台决策树 中被单独标注为 Critical。

选型参考（源自 README 决策树 与 gotchas.md 的平台选择表）：

• API / WebSocket / Cron / Email 处理：Workers（默认，无需--platform）。
• 静态站点 / SSG / 文档站：Pages（--platform=pages）。
• 全栈应用（Next.js / Remix / SvelteKit）：需要 Durable Objects、Queues 等 Workers 专属能力时选 Workers；否则 Pages 提供 Git 集成与分支预览。
• 需要 Git 集成、分支预览：选--platform=pages；需要 Durable Objects、D1、Queues：选 Workers（默认）。

选错平台也没关系——用正确的--platform重新创建即可（见 gotchas.md）。

--framework：Web 框架

--framework仅在--type=web-app时生效，支持 next、remix、astro、react-router、solid、svelte、qwik、vue、angular、hono 十个主流框架。注意各框架在初始化时的差异与已知问题（详见 gotchas.md 的框架专项表）：

--lang与--ts/--no-ts

• --lang=ts|js|python只对--type=hello-world生效，决定 Worker 入口脚本的语言。
• --ts/--no-ts面向--type=web-app，控制是否为 Web 应用开启 TypeScript。官方推荐开启（交互向导默认yes），因为npm run cf-typegen生成的绑定类型（见下文「绑定占位符与类型生成」）依赖 TS 工程。

部署标志（Deployment Flags）

部署标志控制脚手架创建后的动作：

三个标志的实战要点：

• --deploy需要本机已完成认证，即执行过wrangler login（一次性 OAuth 流程），或设置了CLOUDFLARE_API_TOKEN环境变量，详见 Wrangler 认证文档。在 CI 中--deploy会跳过交互询问——但更推荐 CI 中显式传--no-deploy，把部署动作单独交给npm run deploy配合密钥执行（见下文 CI/CD 章节）。
• --git默认初始化为 git 仓库；CI 场景推荐--no-git，因为流水线本身已经处于 git 上下文中，多余的git init可能引发嵌套仓库问题。
• --open在本地交互场景方便直接查看部署结果；CI 中无浏览器环境，不应使用。

高级标志（Advanced Flags）

--template：自定义模板

C3 支持 GitHub 仓库模板与本地路径模板两种来源：

# GitHub 仓库模板（两种写法） npm create cloudflare@latest -- --template=username/repo npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi # 本地路径模板 npm create cloudflare@latest my-app -- --template=../my-template

自定义模板必须在仓库根目录提供c3.config.json声明模板元数据，示例（摘自 patterns.md）：

{ "name": "my-template", "category": "hello-world", "copies": [{ "path": "src/" }, { "path": "wrangler.jsonc" }], "transforms": [{ "path": "package.json", "jsonc": { "name": "{{projectName}}" }}] }

• copies：声明需要复制到目标工程的文件或目录。
• transforms：声明对复制后文件做的改写，{{projectName}}是 C3 提供的占位符，会被替换为实际项目名。若模板名错误或模板仓库不存在，C3 会报Template not found，可到cloudflare/templates仓库核对模板名（见 gotchas.md）。

--existing-script：转换既有项目

把已有脚本「搬进」Cloudflare 工程：

npm create cloudflare@latest . -- --type=pre-existing --existing-script=./build/worker.js

--type=pre-existing与--existing-script必须成对出现，且路径相对于当前执行目录。使用.表示在现有项目目录内就地转换，C3 不会创建新的子目录。转换后的工程同样拥有完整的wrangler.jsonc与 package.json 脚本，可直接npm run dev/npm run deploy。

环境变量（Environment Variables）

C3 读取以下环境变量控制认证与行为（摘自 api.md）：

CLOUDFLARE_API_TOKEN=xxx # 用于部署（CI/CD 场景必需） CLOUDFLARE_ACCOUNT_ID=xxx # 账号 ID CF_TELEMETRY_DISABLED=1 # 禁用遥测上报

• CLOUDFLARE_API_TOKEN：CI/CD 或无浏览器环境下的认证凭据。推荐使用 Dashboard 的「Edit Cloudflare Workers」模板创建令牌（覆盖 Workers、Pages、KV、D1、R2），详细步骤见 Wrangler 认证文档的 API Token 小节。
• CLOUDFLARE_ACCOUNT_ID：账号 ID，可在npx wrangler whoami输出中查看，也可写入wrangler.jsonc的account_id字段。
• CF_TELEMETRY_DISABLED：设为1关闭遥测。本仓库 SKILL.md 也强调，任何wrangler deploy/npm run deploy之前都应先执行npx wrangler whoami验证认证状态。

认证排查速查（源自 auth.md）：Not logged in→ 执行wrangler login或设置CLOUDFLARE_API_TOKEN；Authentication error→ 令牌无效或过期，需在 Dashboard 重新生成；Missing account→ 用wrangler whoami核对账号，并把account_id写入wrangler.jsonc；Token works locally, fails CI→ 令牌作用域到了错误的账号，检查两边 account ID 是否一致；Insufficient permissions→ 令牌缺少所需权限，重建令牌。

退出码（Exit Codes）

C3 的退出码语义简单而明确：

• 0：成功。
• 1：用户主动中止（例如在交互提示中按 Ctrl+C 或选择退出）。
• 2：错误（配置错误、网络失败、模板不存在等）。

在 CI 脚本中可据此区分「用户取消」与「真实失败」：例如当退出码为1时通常无需告警（如超时自动中止），退出码为2时应触发失败通知。

实战示例（Examples）

以下示例全部来自 api.md，并补充了参数说明：

# 1. TypeScript Worker（API） npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --no-deploy # 2. Next.js 部署到 Pages npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts # 3. Astro 博客（创建后立即部署） npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --ts --deploy # 4. CI 非交互场景 npm create cloudflare@latest my-app -- --type=web-app --framework=next --ts --no-git --no-deploy # 5. GitHub 模板 npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi # 6. 转换既有项目 npm create cloudflare@latest . -- --type=pre-existing --existing-script=./build/worker.js

逐条拆解：

1. hello-world Worker：创建my-api目录，TypeScript 入口，不部署。适用于 API / WebSocket / Cron 类项目的最小起点。
2. Next.js on Pages：--platform=pages必不可少，否则默认落到 Workers；--ts开启 TypeScript。
3. Astro 博客：--deploy会立即发布，前提是本机已认证（wrangler login或 API Token）。
4. CI 非交互：把所有交互点（type、framework、ts）全部显式给出，--no-git避免嵌套仓库，--no-deploy把发布留到流水线后续步骤。
5. GitHub 模板：使用官方worker-openapi模板，无需name参数时 C3 会按模板默认值创建或交互询问。
6. 转换既有项目：就地（.）把build/worker.js转换为 Cloudflare 工程。

对应 patterns.md 的快速工作流 还提供了一组等价写法：--type=hello-world --lang=ts --deploy（带部署）、--type=web-app --framework=next --platform=pages --ts --deploy等，可按需选用。

非交互模式与 CI/CD

C3 在 CI 中最常见的坑是「CI 卡在交互提示上」（见 gotchas.md）。解决方法是把下面这些标志全部显式给出：

npm create cloudflare@latest my-app -- \ --type=hello-world --lang=ts --no-git --no-deploy

非交互必需项（源自 patterns.md）：

CI 中的认证通过环境变量注入（GitHub Actions 示例，源自 patterns.md）：

- name: Deploy run: npm run deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Monorepo 支持

C3 会自动检测工作区配置（package.json的 workspaces 字段或pnpm-workspace.yaml），因此在 monorepo 中可以直接在packages/下初始化子包：

cd packages/ npm create cloudflare@latest my-worker -- --type=hello-world --lang=ts --no-deploy

--no-deploy在 monorepo 场景同样推荐，避免每个子包初始化时都触发部署。

生成的工程结构与绑定占位符

C3 创建的项目结构（源自 configuration.md）：

my-app/ ├── src/index.ts # Worker 入口 ├── wrangler.jsonc # Cloudflare 配置 ├── package.json # 脚本 ├── tsconfig.json └── .gitignore

初始wrangler.jsonc：

{ "$schema": "https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json", "name": "my-app", "main": "src/index.ts", "compatibility_date": "2026-01-27" }

绑定占位符（必须替换）

C3 会为 KV / D1 等绑定生成占位符 ID，部署前必须替换为真实资源 ID，否则部署报错：

{ "kv_namespaces": [{ "binding": "MY_KV", "id": "placeholder_kv_id" }], "d1_databases": [{ "binding": "DB", "database_id": "00000000-..." }] }

获取真实 ID（源自 configuration.md 与 wrangler README）：

npx wrangler kv namespace create MY_KV # 返回真实 KV namespace ID npx wrangler d1 create my-database # 返回真实 database_id npx wrangler r2 bucket create my-bucket # R2 存储桶

未替换就部署的典型报错：

Error: Invalid KV namespace ID "placeholder_kv_id"

类型生成与开发脚本

C3 生成的 package.json 脚本（源自 configuration.md）：

{ "scripts": { "dev": "wrangler dev", "deploy": "wrangler deploy", "cf-typegen": "wrangler types" } }

添加绑定后必须重新生成类型：

npm run cf-typegen

生成产物为.wrangler/types/runtime.d.ts，把绑定暴露为类型安全的Env接口：

interface Env { MY_KV: KVNamespace; DB: D1Database; }

如果编辑器报Cannot find name 'KVNamespace'，重新执行npm run cf-typegen并在编辑器中重启 TS server（详见 gotchas.md 的 TypeScript Issues）。配置文件改动后同样需要重跑npm run cf-typegen以同步类型。

创建后的完整工作流

C3 只负责初始化，创建完成后进入「开发 → 类型生成 → 测试 → 部署 → 配置密钥」的标准流程（合并自 README 的 Post-Creation 与 patterns.md 的 Post-Creation Checklist）：

cd my-app # 1. 本地开发（热重载） npm run dev # 2. 为绑定生成 TypeScript 类型 npm run cf-typegen # 3. 部署到 Cloudflare npm run deploy

完整检查清单：

1. 检查wrangler.jsonc—— 确认name、compatibility_date。
2. 替换占位符绑定 ID 为真实资源 ID（wrangler kv namespace create、wrangler d1 create、wrangler r2 bucket create）。
3. 运行npm run cf-typegen生成绑定类型。
4. 本地测试：npm run dev。
5. 部署：npm run deploy。
6. 添加密钥：npx wrangler secret put SECRET_NAME。

若报Feature X requires compatibility_date >= ...，把wrangler.jsonc中的compatibility_date更新为当天日期；若报Node.js version not supported，安装 Node.js 18+（如nvm install 20），详见 gotchas.md。

常见错误速查表

下表汇总 C3 全生命周期的典型错误、原因与修复（摘自 gotchas.md）：

阅读地图：C3 文档体系

skills/.curated/cloudflare-deploy/references/c3/下四份文档各司其职（见 README 的 In This Reference 表格）：

按任务选读：首次建项目读 README；搭 CI/CD 读 README → api → patterns；调试失败部署读 gotchas；理解生成文件读 configuration；完整 CLI 参考读 api；创建自定义模板读 patterns → configuration；转换既有项目读 README → patterns。C3 之外的日常开发与资源管理（KV/D1/R2 的增删改查、wrangler tail实时日志、环境部署与回滚）继续查阅 Wrangler 参考文档，形成「C3 初始化 + Wrangler 运维」的完整闭环。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills