React / 系统课时
部署全栈应用
部署全栈应用
全栈部署不仅是把 Next.js 页面发布出去,还要把生产数据库、环境变量、Schema 迁移和运行进程串成一条可验证的发布链路。完成后,你应该能从公网访问应用,并用健康检查确认应用与数据库都可用。
学习目标
- 准备生产数据库与仅服务端可见的环境变量
- 按“构建 → 迁移 → 启动 → 验证”的顺序发布 Next.js 应用
- 用健康检查和回退边界判断一次发布是否真正成功
明确生产部署链路
生产环境至少有两个独立对象:运行 Next.js 的应用服务,以及保存业务数据的数据库。代码发布可以频繁回滚,数据库 Schema 变化却可能影响新旧两个版本,因此迁移必须被当成发布步骤,而不是某个应用实例启动时顺手执行的命令。

准备数据库与环境变量
先创建生产数据库并拿到生产连接串,确认网络访问、TLS、备份和数据库账号权限符合生产要求。应用侧至少要配置 DATABASE_URL,认证密钥、第三方 API 密钥等也必须通过部署平台的 Secret 或环境变量注入,而不是提交到仓库。
| 变量示例 | 可见范围 | 用途 |
|---|---|---|
DATABASE_URL |
仅服务端 | 连接生产数据库 |
AUTH_SECRET |
仅服务端 | 会话或令牌签名密钥 |
NEXT_PUBLIC_APP_NAME |
客户端可见 | 展示公开应用名称 |
如果项目使用 Prisma,可以在 package.json 中准备独立迁移脚本。下面是配置片段,不包含真实凭据。
{
"scripts": {
"build": "next build",
"start": "next start",
"db:migrate": "prisma migrate deploy"
}
}生效后,部署系统可以把数据库迁移作为独立阶段执行,而不是让每个新实例同时运行迁移。
按顺序构建、迁移和启动
在普通 Node.js 托管环境中,可以用下面的顺序验证发布流程。<PORT> 代表平台分配或你配置的实际端口。
npm ci
npm run build
npm run db:migrate
PORT="<PORT>" npm run start预期结果
npm ci -> exit code 0
npm run build -> exit code 0
npm run db:migrate -> exit code 0
npm run start -> 进程保持运行,并监听 <PORT>如果使用会自动完成构建和启动的托管平台,就把相同逻辑映射到它的 Build、Migration/Release 和 Runtime 阶段。关键不是命令必须完全相同,而是迁移要由单一发布步骤执行,并且只有构建和迁移成功后才让新版本接收正式流量。
增加健康检查并验证访问
仅看到首页能打开还不够,因为静态页面正常并不能证明数据库连接成功。可以提供一个只返回最小状态的健康检查接口,让它执行一次轻量数据库查询。下面是片段示例,假设 db 是项目的 Prisma 客户端。
import { db } from "@/lib/db";
export async function GET() {
try {
await db.$queryRaw`SELECT 1`;
return Response.json({ ok: true }, { status: 200 });
} catch {
return Response.json({ ok: false }, { status: 503 });
}
}部署后,用实际域名替换 <HOST> 再检查状态码和响应体。
HOST="<HOST>"
curl -sS -w '\n%{http_code}\n' "https://${HOST}/api/health"预期输出
{"ok":true}
200健康检查通过后,再完成一次真实验收:登录、读取一条数据库数据、执行一次允许的写操作并重新读取结果。这样可以同时覆盖 HTTPS 访问、会话密钥、数据库连接、读写权限和生产 Schema。
上线失败时按证据回退
如果 next build 失败,先修复依赖、类型或构建期变量,不能跳过构建直接上线;如果迁移失败,应停止新版本发布并检查数据库权限、锁和迁移内容;如果应用已启动但健康检查返回 503,优先检查 DATABASE_URL、网络、TLS 和连接池,而不是反复重启实例。
数据库迁移一旦改变了旧版本无法识别的结构,简单回滚应用代码可能仍然失败。因此生产迁移应尽量保持向后兼容:先新增兼容字段或表,再发布新代码,确认稳定后才清理旧结构。发布完成的验收标准不是“平台显示部署成功”,而是新版本能通过健康检查并完成关键读写路径,同时保留清晰的应用回滚与数据库恢复边界。