unibest环境变量：多环境配置管理

在现代化的跨端开发中，环境变量管理是项目配置的核心环节。unibest框架基于Vite构建，提供了强大而灵活的环境变量管理机制，支持多环境、多平台的精细化配置。本文将深入解析unibest的环境变量体系，帮助你掌握专业级的多环境配置技巧。

环境变量基础架构

unibest采用Vite的环境变量系统，支持.env文件的多环境配置模式：

flowchart TD
    A[环境配置文件] --> B[.env]
    A --> C[.env.development]
    A --> D[.env.production]
    A --> E[.env.local]
    
    B --> F[Vite加载环境变量]
    C --> F
    D --> F
    E --> F
    
    F --> G[TypeScript类型定义]
    G --> H[src/env.d.ts]
    
    F --> I[代码中使用import.meta.env]
    I --> J[构建时替换为实际值]

环境变量文件命名规范

unibest支持以下环境配置文件：

文件名	用途	优先级
.env	全局默认配置	最低
.env.development	开发环境配置	中
.env.production	生产环境配置	中
.env.local	本地覆盖配置	最高

核心环境变量详解

基础配置变量

// src/env.d.ts 类型定义
interface ImportMetaEnv {
  /** 网站标题，应用名称 */
  readonly VITE_APP_TITLE: string
  /** 服务端口号 */
  readonly VITE_SERVER_PORT: string
  /** 后台接口地址 */
  readonly VITE_SERVER_BASEURL: string
  /** H5是否需要代理 */
  readonly VITE_APP_PROXY: 'true' | 'false'
  /** H5代理前缀 */
  readonly VITE_APP_PROXY_PREFIX: string // 一般是/api
  /** 上传图片地址 */
  readonly VITE_UPLOAD_BASEURL: string
  /** 是否清除console */
  readonly VITE_DELETE_CONSOLE: string
}

多平台API地址配置

unibest支持针对不同小程序平台配置独立的API地址：

// 代码中使用示例
let baseUrl = import.meta.env.VITE_SERVER_BASEURL

// 微信小程序不同环境配置
if (__UNI_PLATFORM__ === 'mp-weixin') {
  switch (envVersion) {
    case 'develop': // 开发版
      baseUrl = import.meta.env.VITE_SERVER_BASEURL__WEIXIN_DEVELOP || baseUrl
      break
    case 'trial': // 体验版
      baseUrl = import.meta.env.VITE_SERVER_BASEURL__WEIXIN_TRIAL || baseUrl
      break
    case 'release': // 正式版
      baseUrl = import.meta.env.VITE_SERVER_BASEURL__WEIXIN_RELEASE || baseUrl
      break
  }
}

环境变量实战配置

创建环境配置文件

在项目根目录创建env文件夹，并配置不同的环境文件：

# .env.development - 开发环境
VITE_APP_TITLE=unibest开发版
VITE_SERVER_PORT=9000
VITE_SERVER_BASEURL=http://localhost:3000
VITE_APP_PROXY=true
VITE_APP_PROXY_PREFIX=/api
VITE_UPLOAD_BASEURL=http://localhost:3000/upload
VITE_DELETE_CONSOLE=false

# 微信小程序特定配置
VITE_SERVER_BASEURL__WEIXIN_DEVELOP=https://dev-api.example.com
VITE_SERVER_BASEURL__WEIXIN_TRIAL=https://test-api.example.com
VITE_SERVER_BASEURL__WEIXIN_RELEASE=https://api.example.com

# .env.production - 生产环境
VITE_APP_TITLE=unibest正式版
VITE_SERVER_PORT=9000
VITE_SERVER_BASEURL=https://api.example.com
VITE_APP_PROXY=false
VITE_APP_PROXY_PREFIX=/api
VITE_UPLOAD_BASEURL=https://api.example.com/upload
VITE_DELETE_CONSOLE=true

Vite配置集成

在vite.config.ts中加载环境变量：

export default async ({ command, mode }) => {
  const env = loadEnv(mode, path.resolve(process.cwd(), 'env'))
  const {
    VITE_APP_PORT,
    VITE_SERVER_BASEURL,
    VITE_DELETE_CONSOLE,
    VITE_APP_PROXY,
    VITE_APP_PROXY_PREFIX,
  } = env

  return defineConfig({
    envDir: './env', // 自定义env目录
    server: {
      port: Number.parseInt(VITE_APP_PORT, 10),
      proxy: JSON.parse(VITE_APP_PROXY) ? {
        [VITE_APP_PROXY_PREFIX]: {
          target: VITE_SERVER_BASEURL,
          changeOrigin: true,
          rewrite: path => path.replace(
            new RegExp(`^${VITE_APP_PROXY_PREFIX}`), ''
          ),
        },
      } : undefined,
    },
    define: {
      __VITE_APP_PROXY__: JSON.stringify(VITE_APP_PROXY),
    },
  })
}

高级用法与最佳实践

1. 条件编译与平台检测

// 使用__UNI_PLATFORM__进行平台判断
declare const __UNI_PLATFORM__: 
  'app' | 'h5' | 'mp-alipay' | 'mp-baidu' | 
  'mp-kuaishou' | 'mp-lark' | 'mp-qq' | 
  'mp-tiktok' | 'mp-weixin' | 'mp-xiaochengxu'

// 平台特定的环境变量处理
const getApiBaseUrl = () => {
  if (__UNI_PLATFORM__ === 'h5') {
    return import.meta.env.VITE_SERVER_BASEURL
  } else if (__UNI_PLATFORM__ === 'mp-weixin') {
    // 微信小程序环境判断
    const accountInfo = uni.getAccountInfoSync()
    return import.meta.env[`VITE_SERVER_BASEURL__${accountInfo.miniProgram.envVersion.toUpperCase()}`] 
      || import.meta.env.VITE_SERVER_BASEURL
  }
  return import.meta.env.VITE_SERVER_BASEURL
}

2. 类型安全的环境变量访问

// 创建环境变量工具函数
export const env = {
  get title(): string {
    return import.meta.env.VITE_APP_TITLE
  },
  get baseURL(): string {
    return import.meta.env.VITE_SERVER_BASEURL
  },
  get isProxyEnabled(): boolean {
    return import.meta.env.VITE_APP_PROXY === 'true'
  },
  get platform(): string {
    return __UNI_PLATFORM__
  }
}

// 使用示例
console.log(`应用名称: ${env.title}`)
console.log(`当前平台: ${env.platform}`)

3. 构建优化配置

// 根据环境变量配置构建选项
esbuild: {
  drop: import.meta.env.VITE_DELETE_CONSOLE === 'true' 
    ? ['console', 'debugger'] 
    : ['debugger']
},
build: {
  sourcemap: import.meta.env.VITE_SHOW_SOURCEMAP === 'true'
}

环境变量使用场景示例

路由拦截器中使用

// src/router/interceptor.ts
const loginRoute = import.meta.env.VITE_LOGIN_URL
const isDev = import.meta.env.DEV

// 开发环境跳过登录验证
if (isDev) {
  // 开发环境特殊处理
}

请求封装中使用

// src/http/request/alova.ts
export const baseURLMap = {
  DEFAULT: import.meta.env.VITE_SERVER_BASEURL,
  SECONDARY: import.meta.env.VITE_API_SECONDARY_URL,
}

// src/utils/index.ts
export const getEnvBaseUrl = () => {
  let baseUrl = import.meta.env.VITE_SERVER_BASEURL
  // 平台特定的URL重写逻辑
  return baseUrl
}

上传功能中使用

// src/utils/uploadFile.ts
export const UPLOAD_PATH = {
  USER_AVATAR: `${import.meta.env.VITE_UPLOAD_BASEURL}/user/avatar`,
}

常见问题与解决方案

1. 环境变量未生效

问题：环境变量在代码中访问为undefined 解决方案：

• 确认环境变量以VITE_前缀开头
• 检查.env文件位置是否正确
• 重启开发服务器使配置生效

2. 多环境切换

问题：需要手动切换环境配置文件 解决方案：

# 使用mode参数指定环境
pnpm dev:h5 --mode development
pnpm build:h5 --mode production

3. 敏感信息保护

问题：环境变量中包含敏感信息 解决方案：

• 将敏感信息添加到.gitignore
• 使用.env.local进行本地配置
• 通过CI/CD平台注入环境变量

总结

unibest的环境变量管理系统提供了完整的跨端开发解决方案：

特性	优势	应用场景
多环境支持	开发、测试、生产环境隔离	不同阶段的不同配置
多平台适配	小程序、H5、APP平台差异化配置	平台特定的API地址
类型安全	TypeScript完整类型定义	开发时智能提示
构建优化	根据环境变量优化构建输出	生产环境代码压缩

通过合理运用unibest的环境变量管理机制，你可以实现：

1. 配置集中管理：所有环境相关配置统一管理
2. 环境隔离：不同环境使用不同的配置参数
3. 平台适配：针对不同平台提供差异化配置
4. 安全可控：敏感信息与环境配置分离

掌握unibest的环境变量管理，将显著提升你的跨端开发效率和项目维护性，为大型商业项目提供可靠的基础架构支持。