TypeScript + Cloudflare 全家桶部署项目全流程

我的项目技术栈是TypeScript Cloudflare 全家桶Workers, KV, DB, Pages。基于现在的架构我整理了一份**“从本地到边缘”的部署清单**。这套流程主要依赖Wrangler CLICloudflare 的官方命令行工具来完成。以下是详细的操作步骤️ 第一阶段环境与配置准备在开始部署前确保你的本地环境已经准备就绪。安装/更新 Wrangler CLI如果你还没有安装或者版本较旧请先更新。这是你与 Cloudflare 交互的核心工具。npminstall-gwrangler本地登录授权让 Wrangler 能够操作你的 Cloudflare 账户。npx wrangler login执行后浏览器会弹出授权页面点击 Allow 即可。配置wrangler.toml这是部署的“大脑”。你需要确保项目根目录下有wrangler.toml文件并正确配置了以下内容name: 你的 Worker 名称全局唯一。compatibility_date: 建议设置为当前日期如2026-04-06以确保使用最新的运行时特性。main: 入口文件路径例如src/index.ts。[build]: 配置构建命令。因为是 TS 项目通常需要command npm run build。️ 第二阶段基础设施资源创建你的后端依赖 KV 和 D1 (SQL Database)这些资源需要在云端先创建好并绑定到你的 Worker 上。创建 KV 命名空间如果你的项目还没创建 KV使用以下命令npx wrangler kv:namespace createMY_KV注意命令执行后会返回一个id你需要把这个id复制到wrangler.toml的[[kv_namespaces]]配置中。创建 D1 数据库创建 SQL 数据库npx wrangler d1 create数据库名称同样将返回的database_id填入wrangler.toml的[[d1_databases]]配置中。执行数据库迁移 (Migration)既然代码写完了表结构应该也有了。你需要把 SQL schema 应用到云端的 D1 数据库中npx wrangler d1 migrations apply数据库名称--remote加上--remote表示直接操作云端数据库而不是本地模拟环境。⚙️ 第三阶段环境变量与密钥不要硬编码 API Key 或敏感信息。设置环境变量在wrangler.toml的[vars]部分添加非敏感配置如API_URL。设置密钥 (Secrets)对于敏感信息如API_KEY,DB_PASSWORD使用以下命令加密存储npx wrangler secret put密钥名称系统会提示你输入具体的值输入后这些值会安全地绑定到 Worker 环境中。 第四阶段构建与部署一切准备就绪开始将代码推送到边缘网络。本地预构建检查 (可选但推荐)先跑一下构建看看有没有 TypeScript 类型错误或打包问题npmrun build确保你的package.json中build脚本能正确将 TS 编译为 JS通常使用 esbuild 或 tsc。正式部署执行部署命令Wrangler 会自动打包代码、上传资源并激活 Workernpx wrangler deploy如果你配置了多环境如staging或production可以加上--env production参数。验证部署部署成功后终端会给出一个*.workers.dev的域名。访问该地址检查后端 API 是否响应正常数据库读写是否通畅。 第五阶段前端接入与自定义域名既然你有前端部分且域名在 Cloudflare前端部署 (Pages)如果前端也是静态资源React/Vue等建议推送到Cloudflare Pages。可以在 Dashboard 中关联 GitHub 仓库设置 Build command (如npm run build) 和 Output directory (如dist)实现自动部署。绑定自定义域名在 Worker 或 Pages 的项目设置中找到“Custom Domains”。输入你的域名如api.yourdomain.com。因为你的域名已经在 Cloudflare 解析系统会自动添加 CNAME 记录并签发 SSL 证书无需手动去 DNS 面板操作。 快速部署检查清单为了方便你操作我总结了一个简表步骤关键动作常用命令/备注1. 初始化登录 Cloudflarenpx wrangler login2. 资源配置创建 KV 和 D1npx wrangler kv:namespace create ...npx wrangler d1 create ...3. 数据库应用表结构npx wrangler d1 migrations apply ... --remote4. 密钥注入环境变量npx wrangler secret put API_KEY5. 部署上传代码npx wrangler deploy6. 域名绑定自定义域名在 Dashboard 中操作自动 SSL 避坑小贴士构建产物确保wrangler.toml中的main指向的是构建后的文件通常是dist/index.js或类似路径而不是源文件src/index.ts除非你完全依赖 Wrangler 的自动构建。本地调试在部署前强烈建议使用npx wrangler dev在本地模拟运行。它可以模拟 KV 和 D1 的本地环境能帮你省去很多“部署上去才发现报错”的时间。版本控制建议将wrangler.toml纳入 Git 管理但不要提交包含真实密钥的版本使用wrangler secret管理的密钥不会出现在文件中很安全。按照这个清单走一遍你的项目就能稳稳地跑在 Cloudflare 的全球边缘网络上了如果有具体的报错随时把日志发给我。