React / 系统课时
生产环境配置管理
生产环境配置管理
本课解决同一套全栈代码在开发、测试和生产环境中使用不同配置的问题。完成后,你将能正确管理前端接口地址、后端密钥、数据库连接和环境文件,并在启动阶段发现缺失或错误的生产配置。
学习目标
- 区分前端可公开变量与后端敏感配置
- 使用环境文件和运行时变量管理不同部署环境
- 在应用启动时校验密钥、端口和数据库连接地址
划分配置边界
Vite 会把以 VITE_ 开头的变量打包进浏览器代码,因此这些值必须视为公开信息。前端可以保存接口基础地址、功能开关和构建版本,但不能保存数据库密码、JWT 密钥或第三方私钥。
后端配置只在服务器进程中读取。数据库连接、令牌签名密钥和内部服务凭证应由部署平台、容器编排系统或服务器环境变量注入,不应提交到 Git 仓库。

配置前端接口地址
在前端项目中创建 .env.development 和 .env.production。生产文件只保存可公开值。
# .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 时读取生产配置。前端通过统一模块读取变量,并在缺失时立即报错。
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 在启动阶段校验类型和约束。生产部署时应优先由系统环境变量覆盖文件值。
npm install dotenv zod预期输出
added <COUNT> packages<COUNT> 会因锁文件和已有依赖不同而变化。创建 src/config.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;预期结果。全部变量合法时导出经过类型转换的配置;任一变量缺失或格式错误时,进程在启动服务前退出并指出错误字段。
生产环境可以通过进程管理器或容器注入以下变量。示例中的值必须替换,不能直接用于真实系统。
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预期输出
Server listening on port 3000端口和日志格式取决于项目实现。若 JWT_SECRET 少于 32 个字符,程序应在监听端口前退出,并输出对应字段的校验错误。
管理环境文件和密钥
仓库只提交模板文件,例如 .env.example,用于说明变量名称,不写真实值。开发者本地可以使用 .env,生产环境则由部署系统注入。
# .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 中排除真实环境文件:
.env
.env.local
.env.*.local配置文件示例的生效结果是:开发者能看到所需变量清单,但真实密钥不会进入版本库。可以使用 git status --ignored 验证本地 .env 已被忽略。
验证生产配置
先构建前端和后端,再用生产变量启动服务。验证时至少检查健康接口、前端请求地址和跨域来源。
npm run build
NODE_ENV=production npm run server:start
curl -i http://127.0.0.1:3000/health预期输出
HTTP/1.1 200 OK
Content-Type: application/json
{"status":"ok"}如果应用实际端口不是 3000,将命令中的端口替换为真实值。若启动阶段直接退出,先检查变量是否缺失、URL 格式是否正确,再检查数据库主机是否可达;不要通过删除校验规则来绕过错误。
常见配置错误
最危险的错误是把后端密钥写入 VITE_ 变量,因为它会进入浏览器产物。另一个常见问题是生产服务仍读取开发 .env,导致接口地址、数据库或跨域来源指向本机。
配置值修改后需要重新启动后端;前端构建变量修改后通常需要重新构建静态资源。仅重启 Nginx 不会改变已经打包进 JavaScript 的前端变量。