TanStack Ship 基于 TanStack Start 构建，生产环境运行在 Cloudflare Workers 上，数据与异步任务由 Cloudflare 原生服务承载。
重要
推送到 GitHub 不会自动部署生产环境。发布需在本机执行
pnpm run deploy（不是pnpm deploy）。
平台架构
| 组件 | 职责 | 配置位置 |
|---|---|---|
| Workers | SSR、API、Cron | wrangler.jsonc |
| D1 | 用户、账单、博客、归因 | d1_databases |
| R2 | 文件上传、媒体资产 | r2_buckets + 环境变量 |
| KV | 短链 slug 映射 | kv_namespaces |
| Queues | 邮件活动、工作流 | queues |
前置要求
| 工具 | 版本 |
|---|---|
| Node.js | 20+ |
| pnpm | 10+ |
| Wrangler | 4.x |
| Cloudflare 账号 | 开通 Workers、D1、R2、KV、Queues |
一次性登录：
pnpm wrangler login
推荐阅读顺序
- 本地开发 — 安装依赖、
.dev.vars、本地 D1 - Cloudflare 资源 — 创建 D1/R2/KV/Queues
- 环境变量 — 变量对照表
- 密钥与 API 获取 — OAuth、Stripe 等
- 第三方集成 — Resend 等详细接入
- 生产部署 — 构建与发布
- 验证与故障排查 — 上线清单
本地 vs 生产
| 维度 | 本地 | 生产 |
|---|---|---|
| 环境文件 | .dev.vars | wrangler secret + vars |
| 数据库 | pnpm db:migrate:local | pnpm db:migrate:remote |
客户端变量 VITE_* | .dev.vars / shell | 构建时注入，改后需重新 deploy |
| 绑定 | Vite 模拟 cloudflare:workers | wrangler.jsonc bindings |
须知
本地开发时，Vite 会读取
.dev.vars并模拟 Workers 环境（Stripe、R2、PostHog 等），无需每次连远程 Cloudflare。