全栈 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之外使用回退值。 - 在服务端实现认证和授权。
- 在服务端使用 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
- 已定义备份和速率限制