Cloudflare C3create-cloudflare完全指南用官方脚手架从零搭建 Workers 与 Pages 项目【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读C3create-cloudflare是 Cloudflare 官方的项目脚手架 CLI用于通过模板、TypeScript 与一键部署快速搭建 Workers 和 Pages 项目。本指南基于 skills 仓库 中收录的 C3 参考资料整理而成覆盖从快速开始、平台选型、交互式流程、完整 CLI 参数、生成配置到 CI/CD 实战与故障排查的完整链路读完后你将能用一条命令初始化 Worker API、Next.js/Astro 站点并在本地开发、生成绑定类型、部署与排错之间自如切换。快速开始三条命令覆盖三大场景C3 的定位是Official CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment——即以模板、TypeScript 和即时部署为核心。首次使用时推荐交互式命令C3 会逐步引导你完成项目创建# Interactive首次使用推荐 npm create cloudflarelatest my-app # WorkerAPI/WebSocket/Cron npm create cloudflarelatest my-api -- --typehello-world --ts # Pages静态/SSG/全栈 npm create cloudflarelatest my-site -- --typeweb-app --frameworkastro --platformpages注意 NPM 语法中--之后才是传给 C3 的参数而 Yarn/PNPM 不需要双横线详见下文安装方法一节。其中--typehello-world生成最小可运行的 Worker--typeweb-app则用于生成 Web 框架项目。平台决策树先选 Workers 还是 Pages在创建之前最重要的问题是确定目标平台。C3 决策树给出了清晰的判断路径What are you building? ├─ API / WebSocket / Cron / Email handler │ └─ Workers默认——无需 --platform 标志 │ npm create cloudflarelatest my-api -- --typehello-world ├─ 静态站点 / SSG / 文档站 │ └─ Pages ——必须加 --platformpages │ npm create cloudflarelatest my-site -- --typeweb-app --frameworkastro --platformpages ├─ 全栈应用Next.js/Remix/SvelteKit │ ├─ 需要 Durable Objects、Queues 或 Workers 独有特性 │ │ └─ Workers默认 │ └─ 否则使用 Pages以获得 Git 集成与分支预览 │ └─ 加 --platformpages └─ 转换现有项目 └─ npm create cloudflarelatest . -- --typepre-existing --existing-script./src/worker.ts其中有一条关键提醒原文以Critical标注Pages 项目必须显式传入--platformpages否则 C3 默认创建 Workers 项目。也就是说--platform的默认值是workers这一点在 api.md 的核心参数表中也有明确记录。如果创建后发现平台选错了参考 gotchas.md 的Platform Selection一节直接用正确的--platform标志重新创建即可不需要在既有项目上修补。平台选择的判断维度同样收录在故障排查文档中需求平台Git 集成、分支预览branch previews--platformpagesDurable Objects、D1、QueuesWorkers默认交互式流程七个提问的完整顺序不带任何标志运行时C3 会按以下顺序依次提示README.md 的 Interactive Flow 一节Project name—— 要创建的目录名传入.时使用当前目录Application type——hello-world、web-app、demo、pre-existing、remote-templatePlatform——workers默认或pages仅 web-app 可选项Framework—— 若选择 web-appnext、remix、astro、react-router、solid、svelte等TypeScript——yes推荐或noGit—— 是否初始化 Git 仓库yes或noDeploy—— 是否立即部署yes或no需要先wrangler login理解这个顺序很重要它对应了 C3 内部应用类型 → 平台 → 框架 → 语言 → 工程化 → 部署的决策链也解释了为什么在 CI 中必须把每一步都以参数显式给定否则交互提示会导致流水线挂起详见下文 CI/CD 一节。安装方法NPM / Yarn / PNPM 三种方式C3 通过各包管理器的create协议调用无需显式安装# NPM注意 latest 与 -- 分隔符 npm create cloudflarelatest # Yarn yarn create cloudflare # PNPM pnpm create cloudflarelatest完整 CLI 参数参考api.md 提供了面向脚本化、CI/CD 和高级用法的完整参数文档。调用形式为npm create cloudflarelatest [name] [-- flags] # NPM 需要 -- yarn create cloudflare [name] [flags] pnpm create cloudflarelatest [name] [-- flags]核心参数参数可选值说明--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-app 是否使用 TypeScript部署相关参数参数说明--deploy/--no-deploy是否立即部署交互式会提示CI 中建议显式关闭--git/--no-git是否初始化 Git默认 yes--open部署后自动在浏览器打开高级参数参数说明--templateuser/repoGitHub 模板或本地路径--existing-script./src/worker.ts现有脚本需配合--typepre-existing--categoryai\|database\|realtimedemo 类型筛选需配合--typedemo--experimental启用实验性功能--wrangler-defaults跳过 wrangler 相关提示环境变量CLOUDFLARE_API_TOKENxxx # 用于部署 CLOUDFLARE_ACCOUNT_IDxxx # 账户 ID CF_TELEMETRY_DISABLED1 # 关闭遥测退出码0表示成功1表示用户中止2表示出错。在 CI 脚本中可根据退出码判断是否需要重试或告警。生成的文件结构与 wrangler.jsonc创建完成后C3 会生成一个标准的 Cloudflare 项目骨架configuration.md 的 Output Structure 一节my-app/ ├── src/index.ts # Worker 入口 ├── wrangler.jsonc # Cloudflare 配置 ├── package.json # 脚本 ├── tsconfig.json └── .gitignorewrangler.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 }其中compatibility_date决定运行时行为版本值得特别留意在 gotchas.md 的 Compatibility Date 一节中明确提到当报错Feature X requires compatibility_date ...时需要把该字段更新到当天的日期。name则必须全局唯一否则部署时会出现Worker already exists错误解法是修改wrangler.jsonc中的name。生成的package.json自带三个核心脚本{ scripts: { dev: wrangler dev, deploy: wrangler deploy, cf-typegen: wrangler types } }创建后进入项目即可使用cd my-app # 本地开发热重载 npm run dev # 为绑定生成 TypeScript 类型 npm run cf-typegen # 部署到 Cloudflare npm run deploy绑定Binding占位符与类型生成C3 生成的配置中包含占位符 ID部署前必须替换为真实资源 IDconfiguration.md 的 Binding Placeholders 一节{ kv_namespaces: [{ binding: MY_KV, id: placeholder_kv_id }], d1_databases: [{ binding: DB, database_id: 00000000-... }] }通过 wrangler 创建真实资源并替换npx wrangler kv namespace create MY_KV # 返回真实 ID npx wrangler d1 create my-database # 返回真实 database_id若忘记替换部署会直接失败并报错Error: Invalid KV namespace ID placeholder_kv_id添加绑定之后运行类型生成命令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 服务即可见 gotchas.md 的 TypeScript Issues 一节。创建后清单Post-Creation Checklistconfiguration 与 patterns 两份文档都给出了创建后的标准检查流程合并为完整清单检查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实战模式CI/CD、Monorepo、自定义模板与存量项目patterns.md 覆盖了真实世界的集成场景。常用快速工作流# TypeScript API Worker npm create cloudflarelatest my-api -- --typehello-world --langts --deploy # Next.js on Pages npm create cloudflarelatest my-app -- --typeweb-app --frameworknext --platformpages --ts --deploy # Astro 静态站点 npm create cloudflarelatest my-blog -- --typeweb-app --frameworkastro --platformpages --tsCI/CDGitHub ActionsCI 中必须保证非交互运行否则流水线会挂在提示上gotchas.md 的 CI/CD 一节典型反例是只执行npm create cloudflarelatest my-app而不给任何标志。非交互运行需要显式提供--typevalue # 必填 --no-git # 推荐CI 中通常已在 git 环境内 --no-deploy # 部署单独执行配合 Secrets 注入 --frameworkvalue # web-app 必填 --ts / --no-ts # 必填部署步骤通过环境变量注入凭证- name: Deploy run: npm run deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}对应地本地/交互式环境使用npx wrangler login完成一次性 OAuth 认证见 SKILL.md 的 Authentication 一节部署前可用npx wrangler whoami验证登录状态。MonorepoC3 能自动识别 workspace 配置package.jsonworkspaces 或pnpm-workspace.yaml因此在 monorepo 的包目录内创建子项目即可cd packages/ npm create cloudflarelatest my-worker -- --typehello-world --langts --no-deploy自定义模板支持 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来声明复制与转换规则{ name: my-template, category: hello-world, copies: [{ path: src/ }, { path: wrangler.jsonc }], transforms: [{ path: package.json, jsonc: { name: {{projectName}} }}] }其中copies声明需要复制到目标项目的文件transforms声明以 JSONC 方式对目标文件做的占位替换如{{projectName}}。存量项目改造C3 也能把现有项目接入 Cloudflare# 给现有 Worker 添加 Cloudflare 支持 npm create cloudflarelatest . -- --typepre-existing --existing-script./dist/index.js # 给现有框架应用添加支持 npm create cloudflarelatest . -- --typeweb-app --frameworknext --platformpages --ts常见故障速查gotchas.md 最后给出了错误速查表整理如下错误原因修复Invalid namespace ID绑定使用了占位符创建真实资源并更新配置Not authenticated未登录npx wrangler loginCannot find name KVNamespace缺少类型npm run cf-typegenWorker already exists名称冲突修改nameCI 挂起缺少标志补充--type、--lang、--no-deployTemplate not found模板名错误检查 cloudflare/templates其他值得注意的细节多锁文件冲突若混用包管理器导致问题按所用工具清理多余锁文件如使用 npm 时删除pnpm-lock.yaml。框架专属问题Next.js 的 create-next-app 失败可尝试npm cache clean --force后重试Astro 缺少适配器时安装astrojs/cloudflareRemix 模块报错时升级remix-run/cloudflare*相关包。Node.js 版本报 Node.js version not supported 时安装 Node.js 18如nvm install 20。文档导航按任务阅读对应参考C3 参考集由五份文档组成In This Reference 与 Reading Order 两节按任务选择阅读路径文件用途使用时机api.md完整 CLI 参数参考脚本化、CI/CD、高级用法configuration.md生成文件、绑定、类型理解产物、自定义配置patterns.md工作流、CI/CD、Monorepo真实世界集成gotchas.md故障排查部署被阻塞、出现错误时任务建议阅读创建第一个项目仅 README配置 CI/CDREADME → api → patterns排查部署失败gotchas理解生成文件configuration完整 CLI 参考api创建自定义模板patterns → configuration转换现有项目README → patterns延伸阅读C3 只是 Cloudflare 部署体系的入口创建项目之后可继续深入本仓库中的配套文档workers/README.md —— Workers 运行时、绑定与 APIworkers-ai/README.md —— AI/ML 模型推理pages/README.md —— Pages 专属特性wrangler/README.md —— Wrangler CLI超出初始搭建之外的能力d1/README.md —— SQLite 数据库r2/README.md —— 对象存储从一条npm create cloudflarelatest命令出发C3 覆盖了选平台 → 定模板 → 生代码 → 配绑定 → 本地调试 → 部署上线 → CI/CD 自动化的完整闭环是进入 Cloudflare 开发平台最顺手的起点。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考