安装
运行 TanStack 模板及其本地 D1 数据库。
本指南会将一份全新的模板运行成位于 http://localhost:3000 的本地 Worker。
前置条件
- Node.js 22 LTS —— 推荐用于模板的 Vite 7 工具链。
- pnpm —— 仓库使用的包管理器。
- Cloudflare 账户 —— 远程 D1/R2 与部署时需要，首次本地启动不需要。
- Wrangler —— 已是开发依赖，通过
pnpm wrangler调用，无需全局安装。
不需要本地 PostgreSQL。Cloudflare D1 会通过 Worker 开发环境 （Miniflare）在本地运行。
设置
创建本地环境文件
cp .env.example .env至少设置：
BETTER_AUTH_SECRET=replace-with-a-random-secret
BETTER_AUTH_URL=http://localhost:3000可用 openssl rand -base64 32 生成密钥。运行 pnpm dev 时，Cloudflare
Vite 插件会让 Vite（通过 import.meta.env 读取 VITE_*）与本地 Worker
运行时都能读取 .env。只有直接运行 wrangler dev 时，.dev.vars
才可作为可选后备。
启用 OAuth、邮件、支付、AI 或远程 D1 工具前，请查看 环境变量。
初始化本地 D1
仓库的 drizzle/ 已包含迁移。将它应用到本地 Miniflare 数据库：
pnpm db:migrate:local如果你修改了 schema，或拿到的副本中 drizzle/ 为空，请先生成并审查迁移：
pnpm db:generate
pnpm db:migrate:local这不会修改远程 D1。不要使用 drizzle-kit push；模板使用需审查的 SQL 迁移。
验证安装
- 首页在
http://localhost:3000正常渲染。 - 注册会向本地 D1 写入用户，且没有缺少数据表错误。
- 应用能进入注册成功页面。
- 配置 Resend 后，验证邮件能送达且链接有效。
- 验证并登录后，可以访问
/dashboard。
默认强制邮箱验证。未设置 RESEND_API_KEY 时，邮件辅助函数会返回发送失败；
注册可能完成，但邮件不会送达，账户也无法完成正常登录流程。请配置
邮件，或仅在本地开发中有意关闭验证要求。
包脚本
| 命令 | 用途 |
|---|---|
pnpm dev | 在 3000 端口启动 Vite 与本地 Worker 运行时 |
pnpm build | 构建生产 Worker 与客户端资源 |
pnpm preview | 预览 Vite 生产构建 |
pnpm deploy | 构建后通过 Wrangler 部署 |
pnpm test | 单次运行 Vitest 测试 |
pnpm check | 运行 Biome lint 与格式检查 |
pnpm lint | 运行 Biome lint 诊断 |
pnpm format | 运行 Biome 格式化 |
数据库与 Wrangler 脚本
| 命令 | 用途 |
|---|---|
pnpm db:generate | 根据 Drizzle schema 在 drizzle/ 生成 SQL |
pnpm db:migrate:local | 向本地 Miniflare D1 应用迁移 |
pnpm db:migrate | 向远程 soar-tanstack D1 应用迁移 |
pnpm cf-typegen | 重新生成 Cloudflare 绑定类型 |
pnpm wrangler <command> | 运行仓库内的 Wrangler CLI |
常见首次运行问题
| 症状 | 常见原因 | 修复方法 |
|---|---|---|
注册时出现 no such table | 本地 D1 为空 | 运行 pnpm db:migrate:local |
| 会话或签名错误 | BETTER_AUTH_SECRET 缺失、仍是占位值或频繁改变 | 在 .env 中生成并固定随机值 |
| Cookie、跳转或回调使用错误主机 | BETTER_AUTH_URL 与浏览器 origin 不一致 | 本地使用 http://localhost:3000 |
| 验证/重置邮件未到达 | 未配置 Resend | 设置 RESEND_API_KEY 与有效发件人，或仅在本地放宽验证 |
| GitHub/Google 登录失败 | 缺少凭据或回调 URL | 配置服务商，或隐藏对应按钮 |