React / 系统课时

生产环境配置管理

生产环境配置管理

本课解决同一套全栈代码在开发、测试和生产环境中使用不同配置的问题。完成后,你将能正确管理前端接口地址、后端密钥、数据库连接和环境文件,并在启动阶段发现缺失或错误的生产配置。

学习目标

  • 区分前端可公开变量与后端敏感配置
  • 使用环境文件和运行时变量管理不同部署环境
  • 在应用启动时校验密钥、端口和数据库连接地址

划分配置边界

Vite 会把以 VITE_ 开头的变量打包进浏览器代码,因此这些值必须视为公开信息。前端可以保存接口基础地址、功能开关和构建版本,但不能保存数据库密码、JWT 密钥或第三方私钥。

后端配置只在服务器进程中读取。数据库连接、令牌签名密钥和内部服务凭证应由部署平台、容器编排系统或服务器环境变量注入,不应提交到 Git 仓库。

前后端生产配置来源与流向

配置前端接口地址

在前端项目中创建 .env.development 和 .env.production。生产文件只保存可公开值。

bash
# .env.development
VITE_API_BASE_URL=http://127.0.0.1:3000/api

# .env.production
VITE_API_BASE_URL=https://api.example.com/api

预期结果。开发服务器请求本地后端,生产构建请求 https://api.example.com/api,两个环境不需要修改业务代码。

这是配置文件示例,不会直接产生控制台输出。Vite 在 npm run dev 时读取开发配置,在 npm run build 时读取生产配置。前端通过统一模块读取变量,并在缺失时立即报错。

ts
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

if (!apiBaseUrl) {
  throw new Error('缺少 VITE_API_BASE_URL');
}

export const frontendConfig = {
  apiBaseUrl,
};

预期结果。变量存在时模块导出统一的接口地址;变量缺失时前端在启动或构建阶段直接报错,不会带着空地址继续运行。

构建后,可以在浏览器网络请求中验证接口是否发送到 https://api.example.com/api。不要把任何秘密值放入 VITE_ 变量,即使仓库本身是私有的。

校验后端生产配置

后端使用 dotenv 读取本地环境文件,使用 zod 在启动阶段校验类型和约束。生产部署时应优先由系统环境变量覆盖文件值。

bash
npm install dotenv zod

预期输出

text
added <COUNT> packages

<COUNT> 会因锁文件和已有依赖不同而变化。创建 src/config.ts:

ts
import 'dotenv/config';
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  PORT: z.coerce.number().int().min(1).max(65535),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  CORS_ORIGIN: z.string().url(),
});

const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const config = parsed.data;

预期结果。全部变量合法时导出经过类型转换的配置;任一变量缺失或格式错误时,进程在启动服务前退出并指出错误字段。

生产环境可以通过进程管理器或容器注入以下变量。示例中的值必须替换,不能直接用于真实系统。

bash
export NODE_ENV=production
export PORT=3000
export DATABASE_URL='postgresql://app_user:<PASSWORD>@db.internal:5432/task_app'
export JWT_SECRET='<AT_LEAST_32_RANDOM_CHARACTERS>'
export CORS_ORIGIN='https://app.example.com'
node dist/server.js

预期输出

text
Server listening on port 3000

端口和日志格式取决于项目实现。若 JWT_SECRET 少于 32 个字符,程序应在监听端口前退出,并输出对应字段的校验错误。

管理环境文件和密钥

仓库只提交模板文件,例如 .env.example,用于说明变量名称,不写真实值。开发者本地可以使用 .env,生产环境则由部署系统注入。

bash
# .env.example
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:password@127.0.0.1:5432/task_app
JWT_SECRET=replace-with-at-least-32-characters
CORS_ORIGIN=http://127.0.0.1:5173

同时在 .gitignore 中排除真实环境文件:

text
.env
.env.local
.env.*.local

配置文件示例的生效结果是:开发者能看到所需变量清单,但真实密钥不会进入版本库。可以使用 git status --ignored 验证本地 .env 已被忽略。

验证生产配置

先构建前端和后端,再用生产变量启动服务。验证时至少检查健康接口、前端请求地址和跨域来源。

bash
npm run build
NODE_ENV=production npm run server:start
curl -i http://127.0.0.1:3000/health

预期输出

text
HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

如果应用实际端口不是 3000,将命令中的端口替换为真实值。若启动阶段直接退出,先检查变量是否缺失、URL 格式是否正确,再检查数据库主机是否可达;不要通过删除校验规则来绕过错误。

常见配置错误

最危险的错误是把后端密钥写入 VITE_ 变量,因为它会进入浏览器产物。另一个常见问题是生产服务仍读取开发 .env,导致接口地址、数据库或跨域来源指向本机。

配置值修改后需要重新启动后端;前端构建变量修改后通常需要重新构建静态资源。仅重启 Nginx 不会改变已经打包进 JavaScript 的前端变量。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生产环境配置管理

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

登录哪都通