前端工程化 / 系统课时
组织多环境配置
组织多环境配置
本课把开发、测试、预发布和生产环境整理为一套可合并、可覆盖、可追踪的配置体系。完成后,你可以用同一份 vite.config.ts 构建不同环境,并快速确认最终生效值来自哪一层。
学习目标
- 设计共享配置、模式配置与本地覆盖的层次
- 使用
mode、.env文件和loadEnv生成最终配置 - 通过构建命令与产物检查验证覆盖结果
先确定配置层次
多环境配置应按“共享默认值 → 模式差异 → 运行时注入”的顺序收敛。共享层只放所有环境一致的规则;模式层保存测试、预发布和生产的明确差异;CI/CD 注入只覆盖部署时才确定的值。Vite 会加载通用 .env、本地文件和当前模式文件,模式专用值优先于通用值,启动进程中已存在的环境变量优先级最高。:contentReference[oaicite:0]{index=0}

推荐把可提交的差异放入 .env.[mode],把个人机器差异放入 *.local 并加入忽略列表。敏感值即使只存在于本地文件,也不能使用 VITE_ 前缀;所有该前缀变量都会进入客户端代码,只能承载公开配置。:contentReference[oaicite:1]{index=1}
实现可合并配置
下面的配置为四种模式建立显式映射,再用 mergeConfig 合并共享规则与模式差异。只有需要影响 Vite 配置本身的变量才调用 loadEnv;普通前端变量会由 Vite 自动暴露到 import.meta.env。:contentReference[oaicite:2]{index=2}
import {
defineConfig,
loadEnv,
mergeConfig,
type UserConfig,
} from 'vite'
const sharedConfig: UserConfig = {
server: {
strictPort: true,
},
build: {
sourcemap: false,
},
}
const configsByMode: Record<string, UserConfig> = {
development: {
server: { port: 5173 },
},
test: {
build: { sourcemap: true },
},
staging: {
build: { sourcemap: true },
},
production: {
build: { sourcemap: false },
},
}
export default defineConfig(({ mode }) => {
const modeConfig = configsByMode[mode]
if (!modeConfig) {
throw new Error(`Unsupported Vite mode: ${mode}`)
}
// 这些变量要参与配置计算,因此在配置函数中显式加载。
const env = loadEnv(mode, process.cwd(), 'VITE_')
const deployConfig: UserConfig = {
base: env.VITE_DEPLOY_BASE || '/',
define: {
__APP_ENV__: JSON.stringify(mode),
},
}
return mergeConfig(
mergeConfig(sharedConfig, modeConfig),
deployConfig,
)
})环境文件只保存差异,不复制整套配置:
# .env
VITE_APP_TITLE=Anystack Console
VITE_DEPLOY_BASE=/
# .env.test
VITE_API_BASE=https://test-api.example.com
# .env.staging
VITE_API_BASE=https://staging-api.example.com
VITE_DEPLOY_BASE=/console/
# .env.production
VITE_API_BASE=https://api.example.com
VITE_DEPLOY_BASE=/console/loadEnv 返回字符串,端口、布尔值和数字阈值参与配置计算前必须显式转换。不要把所有配置都塞入环境变量;结构稳定、可代码审查的规则应留在 TypeScript 配置中。
添加构建入口与审计信息
为每个可发布模式提供独立脚本,避免成员手写参数造成模式拼错。构建日志至少记录提交版本、模式和部署基础路径,CI 还应保存本次使用的非敏感变量快照。
{
"scripts": {
"dev": "vite --mode development",
"build:test": "vite build --mode test",
"build:staging": "vite build --mode staging",
"build:production": "vite build --mode production"
}
}运行预发布构建:
npm run build:staging预期输出:
vite v<VERSION> building for staging...
✓ <COUNT> modules transformed.
dist/index.html
✓ built in <TIME>版本号、模块数量和耗时会随项目变化。命令行的 --mode 会决定模式文件与配置函数收到的 mode 值。:contentReference[oaicite:3]{index=3}
验证覆盖是否正确
先检查构建后的 dist/index.html,确认静态资源路径带有 /console/;再搜索产物中的测试域名,确保预发布包没有混入测试地址。若修改 .env 后开发服务器仍使用旧值,应重启 Vite,因为环境文件在启动时加载。:contentReference[oaicite:4]{index=4}
grep -n "/console/" dist/index.html
grep -R "test-api.example.com" dist预期输出:
dist/index.html:<LINE>:<script type="module" crossorigin src="/console/assets/index-<ID>.js"></script>第二条命令没有输出即表示未发现测试域名。若命令返回匹配结果,应依次检查进程环境变量、.env.staging.local、.env.staging 和 .env,按照优先级从高到低定位覆盖来源。