全栈 Next.js 系统
何时使用
用于登录、注册、控制面板、按用户管理数据、上传、计费或自建 API。对于落地页和企业官网，请使用 site-estatico 技能。
创建项目
git clone https://github.com/guibean/nextjs-fullstack-template.git <slug>
cd <slug>
pnpm install
cp .env.example .env
用 openssl rand -base64 48 生成 BETTER_AUTH_SECRET，配置好 DATABASE_URL，然后运行：
pnpm db:migrate
pnpm dev
实施顺序
- 设计数据模型、关系、权限和安全威胁。
- 修改
src/db/schema.ts并运行pnpm db:generate。 - 运行
pnpm db:migrate应用迁移。 - 在
src/env.ts中配置环境变量；不要在SKIP_ENV_VALIDATION之外使用 fallback。 - 在服务端实现认证与授权。
- 使用 Zod 在服务端验证所有输入。
- 添加速率限制、日志、备份和可观测性。
- 然后才开始构建控制面板的 UI。
安全规则
- 切勿暴露
DATABASE_URL、BETTER_AUTH_SECRET、RESEND_API_KEY或TURNSTILE_SECRET_KEY。 - 受保护的 Server Components 中使用
auth.api.getSession({ headers: await headers() })。 - Route Handlers 和 Server Actions 同样需要保护。
- 不要依赖客户端验证。
- 当存在认证、数据库或数据变更时，不要使用
output: "export"。 - 生产环境必须启用邮箱验证、速率限制和密码找回功能。
VPS 部署
- 使用
pnpm build构建，产物位于.next/standalone。 - 包含多阶段 Dockerfile。
- 切换版本前先应用数据库迁移。
- 使用 HTTPS、反向代理和进程管理工具。
- 执行破坏性迁移前务必备份 PostgreSQL。
清单
- 环境变量已验证
- 数据库迁移已应用
- 登录、登出和会话已测试
- 受保护路由在无会话时正确重定向
- 受保护 API 在无会话时正确拒绝
- 表单具有双重验证
-
pnpm lint、pnpm typecheck、pnpm build均通过 - 公共页面 Lighthouse 评分 ≥ 95
- 备份和速率限制已配置