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

我的项目技术栈是 TypeScript + Cloudflare 全家桶（Workers, KV, DB, Pages）。基于现在的架构，我整理了一份**“从本地到边缘”的部署清单**。这套流程主要依赖 Wrangler CLI（Cloudflare 的官方命令行工具）来完成。

以下是详细的操作步骤：

🛠️ 第一阶段：环境与配置准备

在开始部署前，确保你的本地环境已经准备就绪。

1. 安装/更新 Wrangler CLI 如果你还没有安装，或者版本较旧，请先更新。这是你与 Cloudflare 交互的核心工具。

   npm install -g wrangler
   

2. 本地登录授权 让 Wrangler 能够操作你的 Cloudflare 账户。

   npx wrangler login
   

   执行后浏览器会弹出授权页面，点击 Allow 即可。
3. 配置 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 上。

1. 创建 KV 命名空间 如果你的项目还没创建 KV，使用以下命令：

   npx wrangler kv:namespace create "MY_KV"
   

   注意：命令执行后会返回一个 id，你需要把这个 id 复制到 wrangler.toml 的 [[kv_namespaces]] 配置中。

2. 创建 D1 数据库 创建 SQL 数据库：

   npx wrangler d1 create <数据库名称>
   

   同样，将返回的 database_id 填入 wrangler.toml 的 [[d1_databases]] 配置中。

3. 执行数据库迁移 (Migration) 既然代码写完了，表结构应该也有了。你需要把 SQL schema 应用到云端的 D1 数据库中：

   npx wrangler d1 migrations apply <数据库名称> --remote
   

   加上 --remote 表示直接操作云端数据库，而不是本地模拟环境。

⚙️ 第三阶段：环境变量与密钥

不要硬编码 API Key 或敏感信息。

1. 设置环境变量 在 wrangler.toml 的 [vars] 部分添加非敏感配置（如 API_URL）。
2. 设置密钥 (Secrets) 对于敏感信息（如 API_KEY, DB_PASSWORD），使用以下命令加密存储：

   npx wrangler secret put <密钥名称>
   

   系统会提示你输入具体的值，输入后这些值会安全地绑定到 Worker 环境中。

🚀 第四阶段：构建与部署

一切准备就绪，开始将代码推送到边缘网络。

1. 本地预构建检查 (可选但推荐) 先跑一下构建，看看有没有 TypeScript 类型错误或打包问题：

   npm run build
   

   确保你的 package.json 中 build 脚本能正确将 TS 编译为 JS（通常使用 esbuild 或 tsc）。

2. 正式部署 执行部署命令，Wrangler 会自动打包代码、上传资源并激活 Worker：

   npx wrangler deploy
   

   如果你配置了多环境（如 staging 或 production），可以加上 --env production 参数。

3. 验证部署 部署成功后，终端会给出一个 *.workers.dev 的域名。访问该地址，检查后端 API 是否响应正常，数据库读写是否通畅。

🌐 第五阶段：前端接入与自定义域名

既然你有前端部分，且域名在 Cloudflare：

1. 前端部署 (Pages)
   • 如果前端也是静态资源（React/Vue等），建议推送到 Cloudflare Pages。
   • 可以在 Dashboard 中关联 GitHub 仓库，设置 Build command (如 npm run build) 和 Output directory (如 dist)，实现自动部署。
2. 绑定自定义域名
   • 在 Worker 或 Pages 的项目设置中，找到 "Custom Domains"。
   • 输入你的域名（如 api.yourdomain.com）。
   • 因为你的域名已经在 Cloudflare 解析，系统会自动添加 CNAME 记录并签发 SSL 证书，无需手动去 DNS 面板操作。

---

📋 快速部署检查清单

为了方便你操作，我总结了一个简表：

步骤	关键动作	常用命令/备注
1. 初始化	登录 Cloudflare	npx wrangler login
2. 资源配置	创建 KV 和 D1	npx wrangler kv:namespace create ...``npx wrangler d1 create ...
3. 数据库	应用表结构	npx wrangler d1 migrations apply ... --remote
4. 密钥	注入环境变量	npx wrangler secret put API_KEY
5. 部署	上传代码	npx wrangler deploy
6. 域名	绑定自定义域名	在 Dashboard 中操作，自动 SSL

💡 避坑小贴士

• 构建产物：确保 wrangler.toml 中的 main 指向的是构建后的文件（通常是 dist/index.js 或类似路径），而不是源文件 src/index.ts，除非你完全依赖 Wrangler 的自动构建。
• 本地调试：在部署前，强烈建议使用 npx wrangler dev 在本地模拟运行。它可以模拟 KV 和 D1 的本地环境，能帮你省去很多“部署上去才发现报错”的时间。
• 版本控制：建议将 wrangler.toml 纳入 Git 管理，但不要提交包含真实密钥的版本（使用 wrangler secret 管理的密钥不会出现在文件中，很安全）。

按照这个清单走一遍，你的项目就能稳稳地跑在 Cloudflare 的全球边缘网络上了！如果有具体的报错，随时把日志发给我。