mkfast-deploy

Q: How do I install mkfast-deploy?

Run npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill mkfast-deploy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mkfast-deploy/ (personal) or .claude/skills/mkfast-deploy/ (project).

by iamzhihuixDevOps & Cloud

把 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」。

Installs: 128
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill mkfast-deploy

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads mkfast-deploy automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.md Routes 配置策略表）
安全优先 — .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 / 双部署）
域名状态（必问）：<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 文件改动可粘贴版本）

FAQ

What does the mkfast-deploy skill do?

How do I install mkfast-deploy?

Run npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill mkfast-deploy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mkfast-deploy/ (personal) or .claude/skills/mkfast-deploy/ (project).

Which AI agents can use mkfast-deploy?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mkfast-deploy safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mkfast-deploy?

It is published by iamzhihuix in iamzhihuix/happy-claude-skills. It has 128 recorded installs.