React / 系统课时

配置生产构建

配置生产构建

开发模式能运行,不代表应用可以直接上线。本课将准备生产变量清单、构建脚本和 Next.js 输出配置,并用一次本地生产构建提前发现类型、依赖与环境问题。

学习目标

  • 区分构建阶段配置与运行阶段配置
  • 配置可重复执行的安装、构建和启动命令
  • 在部署前验证构建产物与生产启动行为

准备生产变量清单

生产密钥不应写入仓库。可以提交 .env.production.example 说明变量名称和用途,真实值由部署平台、容器编排或进程管理器注入。

bash
# .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 不支持注释,下面字段应合并到项目已有配置中。

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,应先按现有脚手架补齐依赖。

配置部署输出

自托管或制作容器镜像时,可以启用独立输出,让构建结果只包含运行所需文件。下面配置同时关闭无必要的技术标识响应头。

ts
// 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 掩盖缺失包。先执行检查,再构建并查看退出码。

bash
rm -rf .next
npm ci
npm run lint
npm run typecheck
npm run build
echo $?

预期结果

text
...
0

中间日志会随 Next.js、Node.js 和路由数量变化,最后的 0 表示所有命令成功。若任一步失败,Shell 会继续执行后续命令的行为取决于环境;在 CI 中应启用失败即停止,例如脚本开头使用 set -euo pipefail。

本地模拟生产启动

构建成功后,用生产命令启动,而不是继续使用 next dev。标准启动方式适合本地验收;容器部署将在下一课使用独立输出。

bash
PORT=3000 npm run start

预期结果

text
Local: http://localhost:3000

实际日志文字、主机名和端口可能不同。保持进程运行后,在另一个终端检查首页和健康接口。

bash
curl -I http://localhost:3000/
curl -s http://localhost:3000/api/health

预期结果

text
HTTP/1.1 200 OK
...

{"status":"ok","time":"<TIME>"}

如果项目尚未实现健康接口,可以先验证首页和关键业务路由。<TIME> 是动态值,实际内容会不同。

处理典型构建失败

类型错误通常来自开发时未执行完整检查;缺少模块通常来自依赖未写入 package.json 或锁文件不同步;环境变量错误则可能发生在构建阶段导入服务端模块时。

静态生成页面如果在构建时访问数据库,构建环境必须能连接数据库,或者页面需要调整为运行时读取。不要为了让构建通过而写入假的生产密钥,也不要在代码中为缺失密钥设置不安全默认值。

构建验收清单

  • 使用受支持的 Node.js 版本,并在开发、CI 和生产保持一致
  • npm ci、代码检查、类型检查和生产构建全部成功
  • 仓库中不存在真实 .env、私钥和数据库密码
  • .next/standalone、.next/static 与 public 的部署策略明确
  • 使用生产命令启动后,首页、登录、管理页和健康接口行为正常
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置生产构建

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通