安装
在你的机器上运行 Next.js 模板。
本指南带你从全新克隆到应用在 http://localhost:3000 上运行。
前置条件
- Node.js 20.9 或更高版本（Next.js 16 要求 Node 20.9+）。建议使用 LTS 版本。
- pnpm —— 本项目的包管理器。可用
corepack enable启用，或从 pnpm.io 安装。 - PostgreSQL —— 一个可连接的本地或托管数据库。你只需要一个可达的
DATABASE_URL。
启动只需要数据库。邮件、OAuth、支付与 AI 各自需要对应的密钥，但应用在没有它们的 情况下也能启动 —— 这些功能在配置之前保持未激活。参见 环境变量。
配置步骤
安装依赖
pnpm install创建环境文件
复制示例文件，并至少填入 DATABASE_URL 与 Better Auth 相关值：
cp .env.example .env本地启动所需的最小集合：
DATABASE_URL—— 你的 PostgreSQL 连接字符串。BETTER_AUTH_SECRET—— 随机密钥。可用openssl rand -base64 32生成。BETTER_AUTH_URL—— 本地开发使用http://localhost:3000。
其余变量在首次运行时都是可选的。完整参考见 环境变量。
初始化数据库 schema
将 Drizzle schema 推送到数据库：
pnpm exec drizzle-kit push这会创建认证与支付表。schema 以及生产环境迁移的注意事项见 数据库。
验证安装
逐项确认每一层都已打通：
- 首页 在
http://localhost:3000正常加载。 - 数据库 已连接 —— 终端没有连接错误，且
drizzle-kit push顺利完成。 - 注册 —— 在
/register创建一个账户。 - 邮箱验证 —— 注册要求验证邮箱。若未配置 Resend，验证邮件无法发送，登录会 被阻止。见下方提示。
- 仪表盘 —— 验证并登录后可访问
/dashboard。
默认要求邮箱验证（src/lib/auth.ts 中的 requireEmailVerification: true）。
若未设置 RESEND_API_KEY，验证邮件无法投递，新账户也无法登录。本地测试时，请配置
Resend（邮件），或在 src/lib/auth.ts 中临时放宽此设置。
包脚本
以下是 package.json 中定义的脚本：
| 命令 | 作用 |
|---|---|
pnpm dev | 启动 Next.js 开发服务器 |
pnpm build | 生产构建 |
pnpm start | 运行生产构建（需先 build） |
pnpm lint | 运行 Biome 检查（biome check） |
pnpm format | 使用 Biome 格式化（biome format --write） |
数据库命令
Drizzle Kit 通过 pnpm exec 直接调用；它们不是包脚本：
| 命令 | 作用 |
|---|---|
pnpm exec drizzle-kit push | 将 schema 推送到数据库（本地工作流） |
pnpm exec drizzle-kit studio | 打开 Drizzle Studio 浏览数据 |
常见首次运行问题
| 现象 | 可能原因 | 解决 |
|---|---|---|
启动时连接被拒 / ECONNREFUSED | DATABASE_URL 缺失或 PostgreSQL 未运行 | 启动 PostgreSQL 并核对 URL |
| 认证错误 / 会话无效 | BETTER_AUTH_SECRET 缺失或被更改 | 在 .env 中设置稳定的密钥 |
| 注册后无法登录 | 要求邮箱验证但未配置 Resend | 配置 RESEND_API_KEY 或本地放宽验证 |
| OAuth 按钮无反应或报错 | 未设置 GitHub/Google 凭据 | 配置对应提供方或隐藏按钮 —— 见 身份认证 |