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

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

以下是详细的操作步骤：

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

安装/更新 Wrangler CLI
如果你还没有安装，或者版本较旧，请先更新。这是你与 Cloudflare 交互的核心工具。
bash 复制代码
```
npm install -g wrangler
```
本地登录授权
让 Wrangler 能够操作你的 Cloudflare 账户。
bash 复制代码
```
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，使用以下命令：
bash 复制代码
```
npx wrangler kv:namespace create "MY_KV"
```
注意：命令执行后会返回一个 id，你需要把这个 id 复制到 wrangler.toml 的 [[kv_namespaces]] 配置中。
创建 D1 数据库

创建 SQL 数据库：
bash 复制代码
```
npx wrangler d1 create <数据库名称>
```
同样，将返回的 database_id 填入 wrangler.toml 的 [[d1_databases]] 配置中。
执行数据库迁移 (Migration)

既然代码写完了，表结构应该也有了。你需要把 SQL schema 应用到云端的 D1 数据库中：
bash 复制代码
```
npx wrangler d1 migrations apply <数据库名称> --remote
```
加上 --remote 表示直接操作云端数据库，而不是本地模拟环境。

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

设置环境变量
在 wrangler.toml 的 [vars] 部分添加非敏感配置（如 API_URL）。
设置密钥 (Secrets)
对于敏感信息（如 API_KEY, DB_PASSWORD），使用以下命令加密存储：
bash 复制代码
```
npx wrangler secret put <密钥名称>
```
系统会提示你输入具体的值，输入后这些值会安全地绑定到 Worker 环境中。

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

本地预构建检查 (可选但推荐)

先跑一下构建，看看有没有 TypeScript 类型错误或打包问题：
bash 复制代码
```
npm run build
```
确保你的 package.json 中 build 脚本能正确将 TS 编译为 JS（通常使用 esbuild 或 tsc）。
正式部署

执行部署命令，Wrangler 会自动打包代码、上传资源并激活 Worker：
bash 复制代码
```
npx 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. 初始化	登录 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 的全球边缘网络上了！如果有具体的报错，随时把日志发给我。