From open-source-prep
Deploys mkfast-template/TanStarter projects to Cloudflare Workers by auto-detecting enabled components (D1/R2/Email/Better Auth/Stripe/Creem/Beehiiv) and tailoring steps to avoid errors from unused features.
npx claudepluginhub iamzhihuix/happy-claude-skills --plugin open-source-prepThis skill uses the workspace's default tool permissions.
把 `mkfast-template`(TanStarter 系)项目部署到 Cloudflare Workers。**核心价值:根据项目实际启用的组件动态裁剪部署步骤**,避免照搬完整版文档导致裁剪版项目跑空命令甚至报错。
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
把 mkfast-template(TanStarter 系)项目部署到 Cloudflare Workers。核心价值:根据项目实际启用的组件动态裁剪部署步骤,避免照搬完整版文档导致裁剪版项目跑空命令甚至报错。
是:基于 mkfast-template 模板派生的项目,包括完整 SaaS 形态、裁剪版博客、或任意中间形态。
不是:任意 Cloudflare Workers 项目(这种情况用 wrangler skill 就够)。
判断标志(满足任一即可):
wrangler.jsonc + package.jsonpackage.json 含 wrangler + @cloudflare/vite-plugin + @tanstack/react-start 中任一drizzle.config.ts / src/server.ts / src/db/auth.schema.tspnpm run deploy 不算工作完成db:migrate:remote 会找不到 migrations 目录).env.production 含非 VITE_* 变量)必须在 deploy 前推到 Cloudflare,否则运行时崩溃pnpm run deploy 前必须用 AskUserQuestion 让用户最终确认(影响生产域名)routes 的配置,需先去掉 routes、deploy 拿默认域名、再到 Dashboard 绑定(详见 references/tailoring.md Routes 配置策略表).env* 必须进 .gitignore;对话 / 截图 / Slack / commit message 中出现过的 secret 一律视为已泄漏,立即 rotate(见 Phase 1.5 安全 baseline + Phase 4 Secret rotation 提醒)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 失败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):
部署前必查 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 1 / 1.5 画像问用户,按情况选 1-5 题:
references/cn-access.md 切换方案(EdgeOne / Vercel + 国内 CDN / 双部署)<domain> 是否托管在 Cloudflare?三选项:已托管 / 未托管(先用默认 *.workers.dev)/ 还没买wrangler d1 create / wrangler r2 bucket create?裁剪决策树详见 references/tailoring.md。
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)references/components.md 的 §API Token 权限完整矩阵(Workers Scripts / D1 / R2 / Workers Routes / Email / KV 等),缺权限直接到 Dashboard → My Profile → API Tokens 编辑现有 token 加权限(不用重建)pnpm run deploy仅当检测到对应组件时做(按 references/components.md 详细步骤):
pnpm wrangler d1 create <name> → 写回 wrangler.jsonc 的 database_id → pnpm db:migrate:remotepnpm wrangler r2 bucket create <name> → 写回 bucket_namepnpm dlx @better-auth/cli@latest secret 生成 → wrangler secret put BETTER_AUTH_SECRETpnpm wrangler secret bulk .env.production仅当用户在 Phase 2 选了 CI:
.github/workflows/deploy.yml + 提示去 GitHub Settings → Secrets 加 CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN / 全部 VITE_*# 在线验证(首次)
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 命中) |
附加检查:
Total Upload: X KiB / gzip: Y KiB → Y < 3072(3 MB 免费计划上限)<worker-name> → Logs → 无 runtime error上线后 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>
注意:
wrangler d1 execute 应用wrangler r2 object get 备份才行)wrangler secret put <KEY> 覆盖为旧值,或 wrangler secret delete <KEY> 清除Secret rotation 提醒(重要): 如果本次部署过程中 token / API key / database secret 在以下任一渠道出现过:
→ 立即去 Cloudflare Dashboard / 第三方服务后台 roll(生成新值替代旧值)。token 字符串变了的,记得更新 .env.local 和 GitHub Secrets。
报错排查见 references/troubleshoot.md。
每阶段结束后给用户简洁汇报,例:
## Phase 1 — 项目画像
**形态**:裁剪版博客
**启用组件**:无(纯 SSR + 博客)
**待执行步骤**:2 步(whoami + deploy)
**跳过**:D1 / R2 / Email / Auth / Pay / Secret bulk / Migrate
✅ wrangler 登录(账户 zhihui)
✅ pnpm run deploy(gzip 471 KB / 17ms 启动)
✅ HTTP 200 验证通过
⚠️ 可选未启用:Giscus / Plausible
references/components.md — mkfast-template 12 类组件检测信号 → 部署步骤映射表
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 文件改动可粘贴版本)