React / 系统课时
配置生产构建
配置生产构建
开发模式能运行,不代表应用可以直接上线。本课将准备生产变量清单、构建脚本和 Next.js 输出配置,并用一次本地生产构建提前发现类型、依赖与环境问题。
学习目标
- 区分构建阶段配置与运行阶段配置
- 配置可重复执行的安装、构建和启动命令
- 在部署前验证构建产物与生产启动行为
准备生产变量清单
生产密钥不应写入仓库。可以提交 .env.production.example 说明变量名称和用途,真实值由部署平台、容器编排或进程管理器注入。
# .env.production.example
DATABASE_URL=postgresql://<USER>:<PASSWORD>@<HOST>:5432/<DATABASE>
SESSION_SECRET=<LONG_RANDOM_SECRET>
NEXT_PUBLIC_SITE_NAME=Anystack Notes这是配置示例,不会直接产生控制台输出。验证时应确认所有必需变量都能在构建或启动阶段读取,同时确保示例文件中没有真实账号、密码和令牌。
NEXT_PUBLIC_ 变量可能在构建时写入客户端包,因此需要在执行 npm run build 前设置。数据库连接串和会话密钥只应在服务端读取,不能加公开前缀。
固定构建脚本
package.json 中至少保留开发、构建、启动和代码检查命令。标准 JSON 不支持注释,下面字段应合并到项目已有配置中。
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint .",
"typecheck": "tsc --noEmit"
}
}生效行为是:npm run build 生成生产产物,npm run start 启动已构建应用;lint 与 typecheck 在构建前发现代码质量和类型问题。项目若没有独立安装 TypeScript 或 ESLint,应先按现有脚手架补齐依赖。
配置部署输出
自托管或制作容器镜像时,可以启用独立输出,让构建结果只包含运行所需文件。下面配置同时关闭无必要的技术标识响应头。
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
output: 'standalone',
poweredByHeader: false,
}
export default nextConfig这是配置文件,不要求控制台输出。验证方式是构建完成后检查 .next/standalone/server.js 是否存在;静态资源仍需在部署镜像中复制 public 和 .next/static。
执行干净构建
生产构建应从锁文件安装依赖,避免本机已有 node_modules 掩盖缺失包。先执行检查,再构建并查看退出码。
rm -rf .next
npm ci
npm run lint
npm run typecheck
npm run build
echo $?预期结果
...
0中间日志会随 Next.js、Node.js 和路由数量变化,最后的 0 表示所有命令成功。若任一步失败,Shell 会继续执行后续命令的行为取决于环境;在 CI 中应启用失败即停止,例如脚本开头使用 set -euo pipefail。
本地模拟生产启动
构建成功后,用生产命令启动,而不是继续使用 next dev。标准启动方式适合本地验收;容器部署将在下一课使用独立输出。
PORT=3000 npm run start预期结果
Local: http://localhost:3000实际日志文字、主机名和端口可能不同。保持进程运行后,在另一个终端检查首页和健康接口。
curl -I http://localhost:3000/
curl -s http://localhost:3000/api/health预期结果
HTTP/1.1 200 OK
...
{"status":"ok","time":"<TIME>"}如果项目尚未实现健康接口,可以先验证首页和关键业务路由。<TIME> 是动态值,实际内容会不同。
处理典型构建失败
类型错误通常来自开发时未执行完整检查;缺少模块通常来自依赖未写入 package.json 或锁文件不同步;环境变量错误则可能发生在构建阶段导入服务端模块时。
静态生成页面如果在构建时访问数据库,构建环境必须能连接数据库,或者页面需要调整为运行时读取。不要为了让构建通过而写入假的生产密钥,也不要在代码中为缺失密钥设置不安全默认值。
构建验收清单
- 使用受支持的 Node.js 版本,并在开发、CI 和生产保持一致
npm ci、代码检查、类型检查和生产构建全部成功- 仓库中不存在真实
.env、私钥和数据库密码 .next/standalone、.next/static与public的部署策略明确- 使用生产命令启动后,首页、登录、管理页和健康接口行为正常