cloudflare-app-bootstrap

Cloudflare 应用引导

将项目从当前状态推进到能够在本地发起请求，并验证所需应用行为的状态。保留用户使用的框架、包管理器、CLI 和现有服务。选择配置或命令之前，先阅读相关的最新文档；并通过本地 CLI 帮助信息和 schema 检查其是否受已安装的版本支持。

从项目入手

检查应用目录、锁文件、脚本、框架和适配器版本、Cloudflare 配置（cloudflare.config.ts 或 Wrangler 配置文件），以及现有的设置说明。在 monorepo 中，先确定应用根目录，再安装依赖或生成文件。根据现有锁文件安装依赖，并沿用项目的依赖和配置惯例。

如果项目尚无 Cloudflare 配置，请先为框架应用使用 frameworks-on-cloudflare 技能进行设置；否则使用 cf-cli 技能。确定框架生成的配置的来源，并编辑该来源。不要为了修复配置问题而用入门模板替换正常运行的应用。

仅连接应用所需的资源

确定应用代码使用的每个绑定，并将其映射到现有资源或新的本地资源。确保代码和配置中的名称一致。保留现有资源标识符：未设置标识符的绑定会被视为新资源，并在下一次部署时创建。

手动创建受支持的资源前，请阅读自动配置资源，并确认该功能涵盖哪些资源类型。不同 CLI 的资源配置方式有所不同：

• Wrangler： wrangler dev 会创建可在多次运行之间保留的本地资源；wrangler deploy 会创建远程资源，并将其标识符写回配置文件。
• cf： cf deploy 会配置缺失的资源，但不会将标识符写回 cloudflare.config.ts（开发、构建和部署）。请将其报告的标识符记录到配置中。

任何需要创建远程资源的操作开始之前，先确定账户、环境和资源。

根据应用脚本和本地开发指南选择开发命令。本地 Worker 可以使用远程绑定：在执行写入操作之前，确认哪些资源是模拟的，以及哪些调用会访问真实服务。使用框架支持的 Workers 开发集成；仅运行前端开发服务器并不能验证服务端绑定是否正常工作。

对于由数据支持的功能，只初始化首次有意义请求所需的状态。保留现有迁移工具。对于 D1，请遵循迁移指南，并在运行 d1 migrations apply 时显式传入 --local 或 --remote。--local 只会初始化模拟数据库；只有所需设置包含对该数据库的变更时，才应用远程迁移。对于 Durable Objects，请查看当前的类迁移配置，不要将其视为 D1 SQL 迁移。

解析配置和密钥

按使用方对必需值进行分类：构建流程、浏览器包或 Worker 运行时。不要将私有运行时凭据放入公开的客户端配置中。使用 Workers secrets 管理运行时密钥，并在构建环境中配置构建所需的值。

在 Wrangler 和 Vite 项目中，按照本地密钥加载的说明处理文件名、环境优先级和必需密钥声明。在 cf 项目中，使用 cf cli search 查找对应方式，不要假设其行为与 Wrangler 相同。沿用项目选定的本地密钥文件，确保包含真实值的文件已被 Git 忽略，并为缺失的值提供名称和安全的占位值。本地密钥不会安装到已部署的 Worker 上。只有当所选工作流需要访问账户时才进行身份验证；不要将登录或部署设为本地设置的普遍前提。

验证首次应用请求

更改配置后，使用项目脚本重新生成绑定和运行时类型：在 Wrangler 项目中运行 wrangler types，或在 cf 项目中运行 cf workers types。不要手动编辑生成的声明。运行相关的现有构建和类型检查。

启动实际的开发工作流，并测试有代表性的路由或 UI 操作；适用时还要测试其绑定访问。检查响应和预期的状态更改，而不只是确认服务器已启动。如果缺少凭据或本地服务不受支持，请准确说明哪些内容尚未验证，不要声称应用可正常运行。

在项目的设置文档中保留可复现的安装、初始化和开发命令。报告已测试的 URL 或操作、哪些资源是本地的或远程的、仍缺少哪些必需值，以及尚未完成的远程设置。只有当部署属于用户任务时，才继续部署。

技能反馈

如果用户反馈此技能提供了错误或过时的指导，或缺少相关信息，请阅读 references/skill-feedback.md。