快速开始 — ShipKit

准备

Bun，这个仓库唯一使用的包管理器。需要的版本锁在 package.json的 packageManager 字段里。
Node.js 22 或更新版本。即使通过 bun run 启动，Wrangler 和Vite 也还是跑在 Node 上。
openssl，或者任何能生成随机密钥的办法。
一个 Google Cloud 项目，用来拿 OAuth 凭据——想让 Google 登录按钮真正可用时才需要。没有也能先跑起来，见第 2 步。
一个 Cloudflare 账号，部署时才需要。本地开发不用任何账号。

所有东西都在本地运行：dev server 把代码跑在 workerd 里，也就是 Cloudflare 线上用的同一个运行时；本地的 D1 数据库和 R2 存储桶都是磁盘上的文件，位于 .wrangler/state。

1. 克隆并安装

克隆你的 GitHub 账号获得访问权限的那个 ShipKit 仓库，然后安装依赖：

git clone <repository-url> my-app
cd my-app
bun install
bun run cf-typegen     # 生成 worker-configuration.d.ts，即 Env 类型

worker-configuration.d.ts 被 gitignore 了，所以每次新克隆都要跑一次 cf-typegen，编辑器和 bun run typecheck 才能看到 Worker 的类型。如果你打算以后把新版 ShipKit合并进自己的项目，在改写历史或重命名 remote 之前，先读升级。

2. 创建 `.dev.vars`

本地密钥放在 .dev.vars 里，这个文件被 gitignore 了。.dev.vars.example 是完整的键列表，每个键都有注释，复制一份即可：

cp .dev.vars.example .dev.vars
openssl rand -base64 32    # 把输出填为 BETTER_AUTH_SECRET

有四个值是必填的，否则任何涉及认证的请求都跑不通。环境变量在第一次使用时校验，缺失或格式不对的键会让请求直接报错，错误信息里会写明是哪个键。

键	本地取值
`APP_URL`	`http://localhost:3000`（已经填好）
`BETTER_AUTH_SECRET`	刚才生成的随机字符串，至少 16 个字符
`GOOGLE_CLIENT_ID`	Google OAuth 的 client id
`GOOGLE_CLIENT_SECRET`	对应的 secret

如果暂时还没有 Google 凭据，两个 Google 键随便填一个非空的占位值就行。校验能通过，所有页面都能渲染，也可以用邮箱验证码登录；只有 Google 按钮要等填上真实凭据才能用。在 Google那边登记的回调地址是 http://localhost:3000/api/auth/callback/google。要让 One Tap弹出来，同一个 client id 还要填进 src/config/app-config.ts 的 googleClientId。Google 的完整配置见登录。

文件里其余的键都是可选的，现在可以留空：GitHub 登录、支付服务商的密钥、RESEND_API_KEY。没有它们应用照样能跑；每个键打开什么功能，见配置。

环境变量在 dev server 启动时读取，改完 .dev.vars 要重启。

3. 创建本地数据库

bun run db:migrate:local

这一步把 drizzle/ 里的所有迁移应用到本地 D1 数据库。不需要事先开通任何东西：数据库就是.wrangler/state 下的一个文件，第一次用到时自动创建。

另外可以选择填入演示数据，让管理后台和图表不是空的：

bun run db:seed            # 90 天的用户、订阅、订单、积分
bun run db:seed --reset    # 只删掉这些演示数据，别的不动

演示数据的 id 都以 seed- 开头，邮箱用的都是假域名，所以不会和你自己创建的账号混在一起。数据是确定性的，日期相对于你运行它的那一天。

4. 启动 dev server

bun run dev                # http://localhost:3000

打开 http://localhost:3000。落地页、/pricing、/docs、/blog 以及 /zh 下的中文版本都应该能正常渲染。登录之前访问 /dashboard 会被重定向到 /login。

如果 3000 端口被占用，通常是之前的 dev server 还在跑，先把它停掉再启动。

5. 登录

打开 /login。最多有三种登录方式，第一次登录时都会自动创建账号，没有单独的注册流程。

邮箱验证码始终可用。没有 RESEND_API_KEY 时不会真的发邮件，验证码会打印在dev server 的终端里：
```
[auth] no mail provider — code for you@example.com: 123456
```
把它填到登录页即可。验证码十分钟内有效。
Google 在 .dev.vars 里填好真实凭据后可用。
GitHub 只有在 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET 都设置了时才会出现。

登录后会进入 /dashboard。

6. 把自己设为管理员

新账号没有任何角色。用你登录时的邮箱，在本地数据库里给自己升级：

bunx wrangler d1 execute DB --local \
  --command "UPDATE user SET role='admin' WHERE email='you@example.com';"

刷新页面，侧边栏会出现“管理后台”入口，通向 /admin。内置的 admin 角色拥有全部权限；其他角色可以在后台的“设置 → 角色权限”里创建，见权限。

用 Claude Code

如果你用 Claude Code，/setup 这个 skill 会替你走完上面这些步骤：安装依赖、创建.dev.vars 并生成密钥、跑迁移、启动 dev server、检查页面能否正常响应，等你登录一次后再把你设为管理员。需要在浏览器里操作的步骤各有对应的 skill：/google-oauth 配 Google 凭据，/stripe 或 /creem 配支付，/deploy 部署到 Cloudflare。它们的完整介绍见配合 AI agent 开发。

下一步

先把配置过一遍。src/config/app-config.ts 里的应用名称、规范 URL、客服邮箱和法律主体都是占位值，它们会出现在营销页、每一封事务邮件，以及服务条款和隐私政策页面里。
趁代码还没动过，用删除功能删掉用不到的模块。
按支付接好支付。在填入服务商密钥之前，购买按钮显示“即将开放”，不会产生任何扣款。
准备上线时，按部署操作。

准备