tuyv Mkfast Deploy
把 mkfast-template（TanStarter 系）项目部署到 Cloudflare Workers。核心价值：根据项目实际启用的组件动态裁剪部署步骤，避免照搬完整版文档导致裁剪版项目跑空命令甚至报错。
适用范围
是：基于 mkfast-template 模板派生的项目，包括完整 SaaS 形态、裁剪版博客、或任意中间形态。
不是：任意 Cloudflare Workers 项目（这种情况用 wrangler skill 就够）。
判断标志（满足任一即可）：
- 根目录有
wrangler.jsonc+package.json package.json含wrangler+@cloudflare/vite-plugin+@tanstack/react-start中任一- 目录里有 mkfast 特征文件：
drizzle.config.ts/src/server.ts/src/db/auth.schema.ts
重要原则
- 先评估再执行 — 任何 deploy 命令前必须完成 Phase 1，生成裁剪后的步骤清单。直接
pnpm run deploy不算工作完成 - 不要照搬官方文档 — mkfast 完整版文档假设了 D1 + R2 + secret bulk，裁剪版项目跑这些步骤会报错或浪费（例如无 drizzle 配置时跑
db:migrate:remote会找不到 migrations 目录） - secret bulk 是 gating step — 项目有服务端 secret（
.env.production含非VITE_*变量）必须在 deploy 前推到 Cloudflare，否则运行时崩溃 - 生产部署需明确确认 — Phase 3 执行
pnpm run deploy前必须用 AskUserQuestion 让用户最终确认（影响生产域名） - 域名状态决定 routes 策略 — 域名未托管 Cloudflare 时不能直接 deploy 含
routes的配置，需先去掉 routes、deploy 拿默认域名、再到 Dashboard 绑定（详见references/tailoring.mdRoutes 配置策略表） - 安全优先 —
.env*必须进.gitignore；对话 / 截图 / Slack / commit message 中出现过的 secret 一律视为已泄漏，立即 rotate（见 Phase 1.5 安全 baseline + Phase 4 Secret rotation 提醒） - 模板占位符必查 — mkfast-template 派生项目的
wrangler.jsonc有 4 处模板默认值必改（name/routes.pattern/database_id/bucket_name）+ 1 处必关（logpush: true在 Free/Pro plan 必报 code 10023）。见references/components.md§0 占位符识别表；不查就 deploy 会写到模板原作者的 D1 或 deploy 失败
工作流（4 阶段）
Phase 1 — 自动评估（只读）
Step 1.0（必做，block 后续进度）：对照 references/components.md §0 模板默认占位符识别表做 wrangler.jsonc + package.json diff。任何未替换的模板默认值——name="mkfast-template" / routes[0].pattern="demo.tanstarter.dev" / database_id="dc34f04a-3445-4b5c-bf61-c4ec2328e239" / r2.bucket_name="mkfast-template" / logpush: true——都直接 block 进 Phase 2。
这是本 skill 最重要的前置关：不查就 deploy 会（a）写到模板原作者的 D1 数据库；（b）deploy 失败报 code 10023（logpush 企业功能）；（c）routes 冲突。所有这些都是 mkfast-template 派生项目首次部署几乎必踩的坑。
读取项目状态，识别"项目画像"。最少读这 5 个文件：
| 读什么 | 提取什么 |
|---|---|
wrangler.jsonc |
name / routes / d1_databases / r2_buckets / send_email / 其他 binding |
package.json |
name + 依赖中是否含 drizzle-orm / better-auth / stripe / creem / @beehiiv/sdk |
.env.example |
全部支持的变量分类（参照 references/components.md 检测信号表） |
.env.production（若存在） |
已配的变量 vs 未填（空字符串）的变量 |
.env.local（若存在） |
CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN 是否就绪 |
按 references/components.md 的 12 类组件逐一判断启用与否，生成"项目画像"输出（格式参照 templates/deploy-checklist.md）：
- 项目形态：完整 SaaS / 裁剪版博客 / 中间形态
- 启用组件勾选表
- 环境变量缺口表
- 裁剪后的待执行步骤清单（步数）
Phase 1.5 — 安全 baseline（只读 + 必要时新建 .gitignore）
部署前必查 4 项，缺哪个补哪个，不让 secret 流出仓库是底线：
| 项 | 检查命令 | 不通过时的修复 |
|---|---|---|
.gitignore 存在且含 .env* |
grep -E "\.env" .gitignore |
不存在则立即创建含 .env、.env.local、.env.*.local、.env.production、.dev.vars |
| .env.local 不在 git history | git log --all --full-history -- .env.local 输出为空 |
已被 commit 过 → 用 git filter-repo 清掉 + 立即 rotate 涉及的所有 secret |
wrangler.jsonc 无硬编码 secret |
grep 不应见 sk_live_ / re_live_ / whsec_ 等 |
删硬编码，全走 wrangler secret put |
.env.production 无明文 production secret 准备 commit |
`cat .gitignore | grep .env.production` |
裁剪版项目无 .gitignore 时（见过项目还没 git init 但已经写了 .env.local 的情况），先建 .gitignore 再继续 Phase 2。
Phase 2 — 决策点（AskUserQuestion）
基于 Phase 1 / 1.5 画像问用户，按情况选 1-5 题：
- 目标用户地域（强烈推荐先问）：全球 / 仅海外 / 主要面向中国大陆 / 国内+海外都要
- 若选中国大陆 → ⚠️ 警告：Cloudflare 在中国大陆没有 PoP 节点（除非企业版 + 京东云合作），访问体验时通时不通；建议参考
references/cn-access.md切换方案（EdgeOne / Vercel + 国内 CDN / 双部署）
- 若选中国大陆 → ⚠️ 警告：Cloudflare 在中国大陆没有 PoP 节点（除非企业版 + 京东云合作），访问体验时通时不通；建议参考
- 域名状态（必问）：
<domain>是否托管在 Cloudflare？三选项：已托管 / 未托管（先用默认 *.workers.dev）/ 还没买 - D1 / R2 资源（仅完整版）：是否已在 Cloudflare 创建？如未创建，是否同意现在
wrangler d1 create/wrangler r2 bucket create？ - 可选功能：Giscus / 分析 / Webhook / Crisp 是否本次启用？
- CI 自动化：是否同步配 GitHub Actions auto-deploy？
裁剪决策树详见 references/tailoring.md。
Phase 3 — 执行（按裁剪后清单）
Step 0 — Sanity（强烈推荐）：
# 清掉过往 dev 留下的 dist + .vite 缓存
# 避免 chokidar 在 dev 中 EINTR 报错（曾导致 dev server 起不来）
rm -rf dist .vite node_modules/.vite
# 验证 wrangler 凭证已加载（推荐用 .env.local + 一次 source 而非 wrangler login）
# wrangler 不会自动读 vite 系的 .env.local，必须 export 到当前 shell：
set -a && . ./.env.local && set +a && pnpm wrangler whoami
推荐在
package.json里加 alias 一次解决："deploy:cf": "set -a && . ./.env.local && set +a && pnpm run build && wrangler deploy"之后用
pnpm deploy:cf即可，避免每条 wrangler 命令都要 export。
所有项目都要做：
pnpm wrangler whoami验证登录（未登录时检查.env.local凭证或提示wrangler login）- 检查 token 权限：按启用组件查
references/components.md的 §API Token 权限完整矩阵（Workers Scripts / D1 / R2 / Workers Routes / Email / KV 等），缺权限直接到 Dashboard → My Profile → API Tokens 编辑现有 token 加权限（不用重建） - AskUserQuestion 最终确认 →
pnpm run deploy
仅当检测到对应组件时做（按 references/components.md 详细步骤）：
- (有 D1)
pnpm wrangler d1 create <name>→ 写回wrangler.jsonc的database_id→pnpm db:migrate:remote - (有 R2)
pnpm wrangler r2 bucket create <name>→ 写回bucket_name - (有 send_email) Cloudflare Dashboard 启用 Email Routing + 验证 from 邮箱
- (有 Better Auth)
pnpm dlx @better-auth/cli@latest secret生成 →wrangler secret put BETTER_AUTH_SECRET - (有服务端 secret)
pnpm wrangler secret bulk .env.production - (有支付) Stripe/Creem live key + price ID + webhook endpoint 配置
仅当用户在 Phase 2 选了 CI：
- 创建
.github/workflows/deploy.yml+ 提示去 GitHub Settings → Secrets 加CLOUDFLARE_ACCOUNT_ID/CLOUDFLARE_API_TOKEN/ 全部VITE_*
Phase 4 — 验证
# 在线验证（首次）
curl -s -o /dev/null -w "HTTP %{http_code} | size %{size_download}B | time %{time_total}s\n" https://<domain>
# 5-10 秒后再跑一次（验证缓存 + 二次访问性能）
curl -s -o /dev/null -w "HTTP %{http_code} | size %{size_download}B | time %{time_total}s\n" https://<domain>
预期：
| 指标 | 首次 | 二次（warm） |
|---|---|---|
| HTTP code | 200 | 200 |
| size | > 几 KB（SSR 渲染成功） | 同首次或更小（命中缓存） |
| time | < 3s（含冷启动 + CDN 传播） | < 500ms（PoP 命中） |
附加检查：
- deploy 输出里
Total Upload: X KiB / gzip: Y KiB→Y < 3072（3 MB 免费计划上限） - Cloudflare Dashboard → Workers & Pages →
<worker-name>→ Logs → 无 runtime error - 自定义域名首次访问可能有 30s CDN 传播延迟
上线后 30 分钟观察清单：
| 检查项 | 命令 / 位置 | 预期 |
|---|---|---|
| 5xx 响应率 | Dashboard → Workers & Pages → <worker> → Logs → 筛 status >= 500 |
0 条 |
| 版本号匹配 | Dashboard → <worker> → Deployments |
最新 Version ID 与 deploy 输出一致 |
| Analytics 流量 | Dashboard → <worker> → Analytics（或第三方 RUM） |
有正常请求进入 |
| D1 表访问（若启用） | wrangler d1 execute <name> --remote --command "SELECT COUNT(*) FROM user" |
返回数字不报错 |
| R2 bucket 访问（若启用） | wrangler r2 object list <bucket> |
列表返回不报错 |
回滚方案：
# 列出历史版本
pnpm wrangler deployments list
# 回滚到上一版（不传 id）
pnpm wrangler rollback
# 回滚到指定版本
pnpm wrangler rollback <version-id>
注意：
- D1 migrations 是 forward-only，schema 回滚需要手动写 down migration 并
wrangler d1 execute应用 - R2 无版本概念，按需从备份恢复（部署前做过
wrangler r2 object get备份才行） - Secret 回滚：
wrangler secret put <KEY>覆盖为旧值，或wrangler secret delete <KEY>清除
Secret rotation 提醒（重要）： 如果本次部署过程中 token / API key / database secret 在以下任一渠道出现过：
- Claude / ChatGPT 等对话历史
- Slack / Lark / WeChat 消息
- 截图 / 录屏
- 代码注释 / commit message
→ 立即去 Cloudflare Dashboard / 第三方服务后台 roll（生成新值替代旧值）。token 字符串变了的，记得更新 .env.local 和 GitHub Secrets。
报错排查见 references/troubleshoot.md。
输出格式
每阶段结束后给用户简洁汇报，例：
Phase 1 项目画像输出（example）
## Phase 1 — 项目画像
**形态**：裁剪版博客
**启用组件**：无（纯 SSR + 博客）
**待执行步骤**：2 步（whoami + deploy）
**跳过**：D1 / R2 / Email / Auth / Pay / Secret bulk / Migrate
最终 checklist（example）
✅ wrangler 登录（账户 zhihui）
✅ pnpm run deploy（gzip 471 KB / 17ms 启动）
✅ HTTP 200 验证通过
⚠️ 可选未启用：Giscus / Plausible
工具文件
references/components.md— mkfast-template 12 类组件检测信号 → 部署步骤映射表- §0 模板默认占位符识别表（Phase 1 Step 1.0 必查）
- §API Token 权限完整矩阵（按启用组件勾权限的速查表）
- §没 .env.example 时如何反推 secret 列表（读 src/env/*.ts 反推）
references/tailoring.md— 完整版 vs 裁剪版 vs 中间形态裁剪决策树 + 决策矩阵速查表- §陷阱：
enable=false仍需保留 D1 binding（module-load-time 调用getDb()） - §澄清：
enable=false≠ tree-shake（enable 只控 UX，bundle 仍含 SDK）
- §陷阱：
references/troubleshoot.md— 11 个常见报错 + 排查命令 + 修复（含 #10 Logpush / #11 already exists）references/cn-access.md— 中国大陆访问优化 4 档方案（Cloudflare 设置 / 图床 / EdgeOne 反代 / 双部署）templates/deploy-checklist.md— Phase 1 项目画像输出模板 + 最终汇报模板 + AskUserQuestion 模板templates/stub-no-d1-r2.md— 彻底关闭 D1/R2 的代码 stub 模板（4 文件改动可粘贴版本）