Cloudflare C3create-cloudflareCLI 完全参考命令调用、核心参数与 CI/CD 实战指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以skills/.curated/cloudflare-deploy技能仓库中的 C3 CLI Reference 为骨架完整讲解 Cloudflare 官方脚手架 C3create-cloudflare的调用方式、全部命令行标志、环境变量、退出码与实战示例并结合同目录下的 README、configuration.md、patterns.md、gotchas.md 及仓库中的 SKILL.md 展开源码级佐证。读完本文你将能熟练使用 C3 以交互式或全非交互方式创建 Workers 与 Pages 项目、在 CI/CD 中无阻塞地完成脚手架初始化、理解 C3 生成的工程结构与绑定占位符并快速定位部署失败原因。C3 是什么C3create-cloudflare是 Cloudflare 官方的项目脚手架 CLI用于一键创建 Workers 与 Pages 项目内置模板、TypeScript 支持与即时部署能力。它由npm create cloudflarelatest驱动本质上是对模板系统的封装通过--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 负责「日常运维」。命令调用方式InvocationC3 支持三种主流的 Node.js 包管理器调用方式命令形态完全一致仅在使用 npm 与 pnpm 时需要在参数前额外加--分隔符让包管理器把后续参数透传给 C3npm create cloudflarelatest [name] [-- flags] # NPM requires -- yarn create cloudflare [name] [flags] pnpm create cloudflarelatest [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→ 是否初始化 Gityes/no→ 是否立即部署yes/no需要先wrangler login。首次使用建议直接不带任何参数运行让交互向导带你走完整个流程详见 README 的 Interactive Flow 小节。核心标志Core Flags核心标志决定「创建什么样的项目」。完整参数表来自 api.mdFlag取值说明--typehello-world、web-app、demo、pre-existing、remote-template应用类型--platformworkers默认、pages目标平台--frameworknext、remix、astro、react-router、solid、svelte、qwik、vue、angular、honoWeb 框架需配合--typeweb-app--langts、js、python语言用于--typehello-world--ts/--no-ts-是否为 Web 应用启用 TypeScript--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 仓库或本地路径。--platformWorkers 还是 Pages关键提醒CriticalPages 项目必须显式加--platformpages否则 C3 一律默认使用 Workers。这一点在 README 的平台决策树 中被单独标注为 Critical。选型参考源自 README 决策树 与 gotchas.md 的平台选择表API / WebSocket / Cron / Email 处理Workers默认无需--platform。静态站点 / SSG / 文档站Pages--platformpages。全栈应用Next.js / Remix / SvelteKit需要 Durable Objects、Queues 等 Workers 专属能力时选 Workers否则 Pages 提供 Git 集成与分支预览。需要 Git 集成、分支预览选--platformpages需要 Durable Objects、D1、Queues选 Workers默认。选错平台也没关系——用正确的--platform重新创建即可见 gotchas.md。--frameworkWeb 框架--framework仅在--typeweb-app时生效支持 next、remix、astro、react-router、solid、svelte、qwik、vue、angular、hono 十个主流框架。注意各框架在初始化时的差异与已知问题详见 gotchas.md 的框架专项表框架常见问题修复方式Next.jscreate-next-app 失败npm cache clean --force后重试Astro缺少适配器安装astrojs/cloudflareRemix模块错误升级remix-run/cloudflare*--lang与--ts/--no-ts--langts|js|python只对--typehello-world生效决定 Worker 入口脚本的语言。--ts/--no-ts面向--typeweb-app控制是否为 Web 应用开启 TypeScript。官方推荐开启交互向导默认yes因为npm run cf-typegen生成的绑定类型见下文「绑定占位符与类型生成」依赖 TS 工程。部署标志Deployment Flags部署标志控制脚手架创建后的动作Flag说明--deploy/--no-deploy是否立即部署默认交互式询问在 CI 中跳过询问--git/--no-git是否初始化 Git 仓库默认 yes--open部署后是否自动打开浏览器三个标志的实战要点--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 FlagsFlag说明--templateuser/repoGitHub 模板仓库或本地模板路径--existing-script./src/worker.ts既有脚本路径需--typepre-existing--categoryai\|database\|realtime演示筛选需--typedemo--experimental启用实验特性--wrangler-defaults跳过 Wrangler 相关交互提示直接采用默认值--template自定义模板C3 支持 GitHub 仓库模板与本地路径模板两种来源# GitHub 仓库模板两种写法 npm create cloudflarelatest -- --templateusername/repo npm create cloudflarelatest -- --templatecloudflare/templates/worker-openapi # 本地路径模板 npm create cloudflarelatest 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 cloudflarelatest . -- --typepre-existing --existing-script./build/worker.js--typepre-existing与--existing-script必须成对出现且路径相对于当前执行目录。使用.表示在现有项目目录内就地转换C3 不会创建新的子目录。转换后的工程同样拥有完整的wrangler.jsonc与 package.json 脚本可直接npm run dev/npm run deploy。环境变量Environment VariablesC3 读取以下环境变量控制认证与行为摘自 api.mdCLOUDFLARE_API_TOKENxxx # 用于部署CI/CD 场景必需 CLOUDFLARE_ACCOUNT_IDxxx # 账号 ID CF_TELEMETRY_DISABLED1 # 禁用遥测上报CLOUDFLARE_API_TOKENCI/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.mdNot logged in→ 执行wrangler login或设置CLOUDFLARE_API_TOKENAuthentication error→ 令牌无效或过期需在 Dashboard 重新生成Missing account→ 用wrangler whoami核对账号并把account_id写入wrangler.jsoncToken works locally, fails CI→ 令牌作用域到了错误的账号检查两边 account ID 是否一致Insufficient permissions→ 令牌缺少所需权限重建令牌。退出码Exit CodesC3 的退出码语义简单而明确0成功。1用户主动中止例如在交互提示中按 CtrlC 或选择退出。2错误配置错误、网络失败、模板不存在等。在 CI 脚本中可据此区分「用户取消」与「真实失败」例如当退出码为1时通常无需告警如超时自动中止退出码为2时应触发失败通知。实战示例Examples以下示例全部来自 api.md并补充了参数说明# 1. TypeScript WorkerAPI npm create cloudflarelatest my-api -- --typehello-world --langts --no-deploy # 2. Next.js 部署到 Pages npm create cloudflarelatest my-app -- --typeweb-app --frameworknext --platformpages --ts # 3. Astro 博客创建后立即部署 npm create cloudflarelatest my-blog -- --typeweb-app --frameworkastro --ts --deploy # 4. CI 非交互场景 npm create cloudflarelatest my-app -- --typeweb-app --frameworknext --ts --no-git --no-deploy # 5. GitHub 模板 npm create cloudflarelatest -- --templatecloudflare/templates/worker-openapi # 6. 转换既有项目 npm create cloudflarelatest . -- --typepre-existing --existing-script./build/worker.js逐条拆解hello-world Worker创建my-api目录TypeScript 入口不部署。适用于 API / WebSocket / Cron 类项目的最小起点。Next.js on Pages--platformpages必不可少否则默认落到 Workers--ts开启 TypeScript。Astro 博客--deploy会立即发布前提是本机已认证wrangler login或 API Token。CI 非交互把所有交互点type、framework、ts全部显式给出--no-git避免嵌套仓库--no-deploy把发布留到流水线后续步骤。GitHub 模板使用官方worker-openapi模板无需name参数时 C3 会按模板默认值创建或交互询问。转换既有项目就地.把build/worker.js转换为 Cloudflare 工程。对应 patterns.md 的快速工作流 还提供了一组等价写法--typehello-world --langts --deploy带部署、--typeweb-app --frameworknext --platformpages --ts --deploy等可按需选用。非交互模式与 CI/CDC3 在 CI 中最常见的坑是「CI 卡在交互提示上」见 gotchas.md。解决方法是把下面这些标志全部显式给出npm create cloudflarelatest my-app -- \ --typehello-world --langts --no-git --no-deploy非交互必需项源自 patterns.md标志是否必需说明--typevalue必需缺失则进入交互询问--no-git推荐CI 本身已在 git 中避免嵌套--no-deploy推荐部署单独用密钥执行--frameworkvalueweb-app 必需否则交互询问框架--ts/--no-ts必需显式声明是否 TypeScriptCI 中的认证通过环境变量注入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 cloudflarelatest my-worker -- --typehello-world --langts --no-deploy--no-deploy在 monorepo 场景同样推荐避免每个子包初始化时都触发部署。生成的工程结构与绑定占位符C3 创建的项目结构源自 configuration.mdmy-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 READMEnpx 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 Checklistcd my-app # 1. 本地开发热重载 npm run dev # 2. 为绑定生成 TypeScript 类型 npm run cf-typegen # 3. 部署到 Cloudflare npm run deploy完整检查清单检查wrangler.jsonc—— 确认name、compatibility_date。替换占位符绑定 ID 为真实资源 IDwrangler kv namespace create、wrangler d1 create、wrangler r2 bucket create。运行npm run cf-typegen生成绑定类型。本地测试npm run dev。部署npm run deploy。添加密钥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错误原因修复Invalid namespace ID占位符绑定创建真实资源并更新配置Not authenticated未登录npx wrangler loginCannot find KVNamespace缺少类型npm run cf-typegenWorker already exists名称冲突修改wrangler.jsonc中的nameCI 卡住缺少必要标志补全--type、--lang、--no-deployTemplate not found模板名错误到 cloudflare/templates 核对模板名多锁文件冲突npm 与 pnpm 锁文件并存删除多余的pnpm-lock.yaml或package-lock.json认证失败 / 令牌失效凭据无效或过期重新生成 API Token核对 account ID阅读地图C3 文档体系skills/.curated/cloudflare-deploy/references/c3/下四份文档各司其职见 README 的 In This Reference 表格文件定位适用场景api.md完整 CLI 标志参考脚本化、CI/CD、高级用法即本文主体configuration.md生成文件、绑定、类型理解输出结构、定制工程patterns.md工作流、CI/CD、monorepo真实世界集成gotchas.md故障排查部署受阻、报错时按任务选读首次建项目读 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考