环境变量

tui-vitex 编译器支持 Vite 风格的环境变量配置，允许开发者通过 .env 文件来管理不同环境的配置，提高开发效率和部署灵活性。

环境变量文件

文件命名规范

tui-vitex 支持以下环境变量文件：

文件名	环境	描述
.env	所有环境	基础环境变量文件
.env.local	所有环境	本地环境变量文件（不提交到版本控制）
.env.development	开发环境	开发环境专用变量
.env.production	生产环境	生产环境专用变量
.env.test	测试环境	测试环境专用变量

文件格式

环境变量文件使用简单的键值对格式：

# .env.development
VITE_API_BASE_URL=https://dev-api.example.com
VITE_APP_TITLE=Development App
VITE_DEBUG_MODE=true

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=Production App
VITE_DEBUG_MODE=false

使用环境变量

在 JavaScript/TypeScript 中使用

// 访问环境变量
const apiUrl = import.meta.env.VITE_API_BASE_URL;
const appTitle = import.meta.env.VITE_APP_TITLE;
const debugMode = import.meta.env.VITE_DEBUG_MODE === 'true';

// 使用环境变量
function fetchData() {
  return fetch(`${apiUrl}/data`);
}

在模板中使用

<view class="app-container">
  <text class="app-title">{{ import.meta.env.VITE_APP_TITLE }}</text>
  <button @click="fetchData">获取数据</button>
</view>

在 CSS 中使用

:root {
  --app-primary-color: {% raw %}{{ import.meta.env.VITE_PRIMARY_COLOR }}{% endraw %};
}

.app-container {
  background-color: var(--app-primary-color);
}

环境变量处理

处理原理

tui-vitex 使用 dotenv 库来处理环境变量：

1. 加载文件：根据当前环境加载对应的 .env 文件
2. 解析变量：解析文件中的键值对
3. 注入变量：将变量注入到 import.meta.env 中
4. 替换变量：在编译过程中替换代码中的环境变量引用

内置环境变量

除了自定义环境变量外，tui-vitex 还提供了一些内置环境变量：

变量名	描述	示例值
import.meta.env.MODE	当前环境模式	development
import.meta.env.PROD	是否为生产环境	false
import.meta.env.DEV	是否为开发环境	true
import.meta.env.BASE_URL	应用基础 URL	/
import.meta.env.UNI_PLATFORM	当前平台	h5

配置示例

开发环境配置

# .env.development
VITE_API_BASE_URL=https://dev-api.example.com
VITE_WS_URL=wss://dev-ws.example.com
VITE_APP_VERSION=1.0.0-dev
VITE_LOG_LEVEL=debug

生产环境配置

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_WS_URL=wss://ws.example.com
VITE_APP_VERSION=1.0.0
VITE_LOG_LEVEL=info

环境变量安全

注意事项

1. 敏感信息：不要在环境变量文件中存储敏感信息（如数据库密码、API 密钥）
2. 版本控制：.env.local 文件应该添加到 .gitignore 中
3. 环境隔离：不同环境的配置应该分开管理
4. 变量命名：所有自定义环境变量必须以 VITE_ 开头

安全最佳实践

• 使用环境变量管理服务端配置
• 敏感信息使用密钥管理服务
• 定期轮换环境变量中的密钥
• 对环境变量文件进行加密存储

性能优化

1. 缓存机制：环境变量在构建时会被缓存，提高构建速度
2. 按需加载：只加载当前环境需要的变量
3. 最小化：生产环境下会移除未使用的环境变量

常见问题

环境变量未定义

• 检查文件命名是否正确
• 确认变量名是否以 VITE_ 开头
• 重新启动开发服务器
• 检查文件路径是否正确

环境变量不生效

• 确认当前环境是否正确
• 检查变量名是否拼写正确
• 重新构建项目
• 查看控制台错误信息

环境变量泄露

• 检查是否将 .env 文件提交到版本控制
• 确认生产环境的敏感信息是否被正确保护
• 使用环境变量加密工具

最佳实践

1. 统一管理：将所有环境相关的配置集中在 .env 文件中
2. 环境隔离：为不同环境创建独立的配置文件
3. 文档化：为环境变量添加注释和文档
4. 版本控制：对环境配置文件进行版本控制（除了包含敏感信息的文件）
5. 自动化：使用 CI/CD 工具自动管理环境变量

通过合理使用环境变量，你可以轻松管理不同环境的配置，提高开发效率和部署灵活性，同时确保应用的安全性和可维护性。