/mkfast-deploy

name: mkfast-deploy
description: 把 mkfast-template / TanStarter 系项目部署到 Cloudflare Workers —— 自动检测实际启用的组件（D1 / R2 / Email / Better Auth / Stripe / Creem / Beehiiv / 通知 / 分析），动态裁剪部署步骤。Use PROACTIVELY whenever 用户提到部署、上线、deploy 到 Cloudflare、wrangler、pnpm deploy、推到生产、发布站点、CF Workers 上线 —— 即使用户没明确说 "mkfast"，只要项目含 `wrangler.jsonc` + `@tanstack/react-start` 或 `drizzle-orm` / `better-auth` 任一，就**优先使用此 skill 而非通用 wrangler / cloudflare skill**（本 skill 更懂 mkfast 的占位符、logpush 默认值陷阱、enable=false 陷阱、tailoring 策略）。SKIP when 项目明显不是 mkfast-template 派生（无 wrangler.jsonc + 无 @tanstack/react-start）→ 改用通用 wrangler skill。触发词：「部署到 Cloudflare」「deploy to Cloudflare」「mkfast 部署」「TanStarter 上线」「wrangler deploy」「准备部署」「上线前要做什么」「deploy 流程」「pnpm deploy」「推到 Cloudflare 生产」「ship to CF」「go live」「发布 CF Workers」「production deploy」「把网站上线」「上线我的 SaaS」。
user-invocable: true

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`

重要原则

1. **先评估再执行** — 任何 deploy 命令前必须完成 Phase 1，生成裁剪后的步骤清单。直接 `pnpm run deploy` 不算工作完成 2. **不要照搬官方文档** — mkfast 完整版文档假设了 D1 + R2 + secret bulk，**裁剪版项目跑这些步骤会报错或浪费**（例如无 drizzle 配置时跑 `db:migrate:remote` 会找不到 migrations 目录） 3. **secret bulk 是 gating step** — 项目有服务端 secret（`.env.production` 含非 `VITE_*` 变量）必须在 deploy 前推到 Cloudflare，否则运行时崩溃 4. **生产部署需明确确认** — Phase 3 执行 `pnpm run deploy` 前必须用 AskUserQuestion 让用户最终确认（影响生产域名） 5. **域名状态决定 routes 策略** — 域名未托管 Cloudflare 时不能直接 deploy 含 `routes` 的配置，需先去掉 routes、deploy 拿默认域名、再到 Dashboard 绑定（详见 `references/tailoring.md` Routes 配置策略表） 6. **安全优先** — `.env*` 必须进 `.gitignore`；**对话 / 截图 / Slack / commit message 中出现过的 secret 一律视为已泄漏**，立即 rotate（见 Phase 1.5 安全 baseline + Phase 4 Secret rotation 提醒） 7. **模板占位符必查** — 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` | 生产 secret 走 `wrangler secret bulk` 不进 git |

**裁剪版项目无 .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 / 双部署）
• **域名状态**（必问）：`<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 一次解决： > ```json > "deploy:cf": "set -a && . ./.env.local && set +a && pnpm run build && wrangler deploy" > ``` > 之后用 `pnpm deploy:cf` 即可，避免每条 wrangler 命令都要 export。

**所有项目都要做**： 1. `pnpm wrangler whoami` 验证登录（未登录时检查 `.env.local` 凭证或提示 `wrangler login`） 2. 检查 token 权限：按启用组件查 `references/components.md` 的 §API Token 权限完整矩阵（Workers Scripts / D1 / R2 / Workers Routes / Email / KV 等），缺权限直接到 Dashboard → My Profile → API Tokens 编辑现有 token 加权限（不用重建） 3. **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`
• (有 s