快速开始

前置要求

工具	版本	说明
Node.js	24.x	生成器和项目锁定在 Node 24
pnpm	10.x	项目使用 pnpm workspace 与 lockfile
PostgreSQL	14+	本地 PostgreSQL、Neon 或其他兼容服务

生成项目

常规 SaaS 项目：

pnpm dlx create-nextdevtpl@latest my-app --preset saas --target vercel
cd my-app

只需要认证和 Dashboard 时：

pnpm dlx create-nextdevtpl@latest my-app --preset minimal

需要运营工具包时：

pnpm dlx create-nextdevtpl@latest my-ops \
  --preset custom \
  --modules auth,analytics,operations \
  --payment stripe \
  --alerts webhook \
  --analytics posthog

三个官方预设和自定义参数见生成器与预设。

查看生成清单

Get-Content nextdevtpl.generated.json

其中记录实际模块、适配器和部署目标。后续只配置这里列出的能力。

配置环境变量

Copy-Item .env.example .env.local

macOS 或 Linux：

cp .env.example .env.local

基础启动至少需要：

DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
BETTER_AUTH_SECRET="replace-with-a-long-random-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

.env.example 已按生成选择裁剪。OAuth、支付、邮件、存储、AI、任务和限流按需 填写，详细变量见配置说明。

初始化并启动

新本地数据库可以直接同步 Schema：

pnpm db:push
pnpm dev

打开 http://localhost:3000。共享环境和生产环境使用迁移：

pnpm db:generate:init
pnpm db:migrate

检查生成的 SQL 后再提交迁移文件。

首次验证

检查	预期结果
首页	带 marketing 时 /en 和 /zh 可访问
注册登录	邮箱密码账号可以进入 /dashboard
文档	带 marketing 时 /en/docs 和 /zh/docs 可访问
健康检查	/api/health 返回 HTTP 200 和 healthy
可选服务	只验证 nextdevtpl.generated.json 中选中的适配器
运营模块	选择后用管理员账号打开 /admin/operations，再使用 CRON_SECRET 调用快照和告警接口

提交前运行：

pnpm format
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build

准备上线时进入部署。