安装
在本地运行 Nuxt 模板。
本指南将带你从全新克隆到应用运行在 http://localhost:3000。
前置条件
- Node.js 20 或更高版本 —— 请使用处于活跃维护期的 LTS 版本。Dockerfile 基于 Node 22 构建，推荐使用该版本。
- pnpm —— 项目的包管理器（
packageManager: pnpm@10.18.3）。可通过corepack enable启用，或从 pnpm.io 安装。 - PostgreSQL —— 一个本地或托管的数据库，只需一个可连接的
NUXT_DATABASE_URL。
仅需数据库即可启动。邮件、OAuth、支付与 AI 各自需要对应的密钥，但应用在没有它们时 也能启动 —— 这些功能在配置之前保持未激活状态。参见 环境变量。
安装步骤
创建环境变量文件
复制示例文件，并至少填写数据库与 Better Auth 相关值：
cp .env.example .env本地启动的最小集合：
NUXT_DATABASE_URL—— 你的 PostgreSQL 连接字符串。NUXT_BETTER_AUTH_SECRET—— 一个随机密钥，可用openssl rand -base64 32生成。NUXT_PUBLIC_BASE_URL—— 本地开发填http://localhost:3000。它驱动 Better Auth 的baseURL与trustedOrigins。
首次运行时其余变量均为可选。完整参考见 环境变量。
初始化数据库 schema
本模板采用 generate/migrate 工作流。先从 Drizzle schema 生成 SQL 迁移，再应用：
npx drizzle-kit generate
npx drizzle-kit migrateDrizzle 配置位于 server/database/drizzle/drizzle.config.ts，并从 Nuxt 运行时
配置读取 NUXT_DATABASE_URL。首次 generate 会创建迁移目录；migrate 会创建
认证与支付表。schema 与生产注意事项见 数据库。
启动开发服务器
pnpm dev打开 http://localhost:3000。dev 脚本运行
nuxt dev --host，会同时在局域网内暴露应用 —— 如果 Better Auth 拒绝了某个局域网
来源，将其加入 NUXT_AUTH_EXTRA_TRUSTED_ORIGINS。
验证安装
逐项确认每一层都已打通：
- 首页在
http://localhost:3000正常加载。 - 数据库连接正常 —— 终端无连接错误，且
drizzle-kit migrate成功完成。 - 注册 —— 在
/auth/register创建账号。 - 邮箱验证 —— 注册要求验证邮箱。未配置 Resend 时，验证邮件无法发送， 登录会被阻止。参见下方提示。
- 仪表盘 —— 验证并登录后，可访问
/dashboard。
默认强制开启邮箱验证（server/utils/auth.ts 中的
requireEmailVerification: true）。若未设置 NUXT_RESEND_API_KEY，验证邮件
无法投递，新账号也无法登录。本地测试时，请配置 Resend
（邮件）或临时在 server/utils/auth.ts 中放宽该设置。
包脚本
package.json 中定义的脚本：
| 命令 | 作用 |
|---|---|
pnpm dev | 启动 Nuxt 开发服务器（nuxt dev --host） |
pnpm build | 生产构建（Nitro .output） |
pnpm generate | 静态站点生成 |
pnpm preview | 本地预览生产构建 |
pnpm postinstall | 运行 nuxt prepare（安装后自动执行） |
使用 ESLint 检查：
pnpm eslint .数据库命令
Drizzle Kit 直接调用；它们是命令，而非包脚本：
| 命令 | 作用 |
|---|---|
npx drizzle-kit generate | 从 schema 生成 SQL 迁移 |
npx drizzle-kit migrate | 将待应用的迁移作用到数据库 |
npx drizzle-kit studio | 打开 Drizzle Studio 浏览数据 |
常见首次运行问题
| 现象 | 可能原因 | 解决 |
|---|---|---|
启动时连接被拒 / ECONNREFUSED | NUXT_DATABASE_URL 缺失或 PostgreSQL 未运行 | 启动 PostgreSQL 并核对 URL |
| 认证错误 / 会话无效 | NUXT_BETTER_AUTH_SECRET 缺失或被更改 | 在 .env 中设置一个稳定的密钥 |
| 注册后无法登录 | 强制邮箱验证但未配置 Resend | 配置 NUXT_RESEND_API_KEY 或在本地放宽验证 |
| OAuth 按钮无反应或报错 | 未设置 GitHub/Google 凭据 | 配置对应提供商或隐藏按钮 —— 参见 身份认证 |