前端工程化 / 系统课时

组织多环境配置

组织多环境配置

本课把开发、测试、预发布和生产环境整理为一套可合并、可覆盖、可追踪的配置体系。完成后,你可以用同一份 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}

ts
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,
  )
})

环境文件只保存差异,不复制整套配置:

bash
# .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 还应保存本次使用的非敏感变量快照。

json
{
  "scripts": {
    "dev": "vite --mode development",
    "build:test": "vite build --mode test",
    "build:staging": "vite build --mode staging",
    "build:production": "vite build --mode production"
  }
}

运行预发布构建:

bash
npm run build:staging

预期输出:

text
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}

bash
grep -n "/console/" dist/index.html
grep -R "test-api.example.com" dist

预期输出:

text
dist/index.html:<LINE>:<script type="module" crossorigin src="/console/assets/index-<ID>.js"></script>

第二条命令没有输出即表示未发现测试域名。若命令返回匹配结果,应依次检查进程环境变量、.env.staging.local、.env.staging 和 .env,按照优先级从高到低定位覆盖来源。

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

目录与阅读设置

阅读设置

17

记录一个想法

组织多环境配置

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

登录哪都通