185 lines
6.3 KiB
Markdown
185 lines
6.3 KiB
Markdown
# 移动端环境变量配置说明
|
||
|
||
## 📋 概述
|
||
|
||
移动端工程已支持通过 `.env` 文件进行环境配置管理，方便在不同环境（开发、测试、生产）之间切换配置，无需修改代码。
|
||
|
||
## 📁 环境变量文件
|
||
|
||
项目包含以下环境变量文件：
|
||
|
||
- **`.env.example`** - 环境变量配置示例文件（应提交到 Git）
|
||
- **`.env.development`** - 开发环境配置（应提交到 Git）
|
||
- **`.env.production`** - 生产环境配置（应提交到 Git）
|
||
- **`.env.local`** - 本地覆盖配置（**不应提交到 Git**，已在 `.gitignore` 中忽略）
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 使用默认配置
|
||
|
||
项目已包含开发和生产环境的默认配置，可以直接使用：
|
||
|
||
```bash
|
||
# 开发环境（自动使用 .env.development）
|
||
npm run dev:h5
|
||
|
||
# 生产环境构建（自动使用 .env.production）
|
||
npm run build:h5
|
||
```
|
||
|
||
### 2. 自定义本地配置
|
||
|
||
如果需要覆盖某些配置，可以创建 `.env.local` 文件：
|
||
|
||
```bash
|
||
# 复制示例文件
|
||
cp .env.example .env.local
|
||
|
||
# 编辑 .env.local，修改需要的配置项
|
||
```
|
||
|
||
`.env.local` 中的配置会覆盖 `.env.development` 或 `.env.production` 中的同名配置。
|
||
|
||
## 📝 配置项说明
|
||
|
||
### API 服务器配置
|
||
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境默认值 |
|
||
|--------|------|---------------|---------------|
|
||
| `VUE_APP_API_BASE_URL` | API基础地址 | `/api` | `/prod-api` |
|
||
| `VUE_APP_DEV_SERVER_URL` | 开发服务器完整地址 | `http://localhost:8080` | `https://api.example.com` |
|
||
| `VUE_APP_REQUEST_TIMEOUT` | 请求超时时间（毫秒） | `300000` (5分钟) | `300000` |
|
||
| `VUE_APP_REPEAT_SUBMIT_INTERVAL` | 防重复提交间隔（毫秒） | `500` | `500` |
|
||
|
||
### 前端域名配置
|
||
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境默认值 |
|
||
|--------|------|---------------|---------------|
|
||
| `VUE_APP_FRONTEND_URL` | 前端域名（用于referer等） | `http://localhost/login?redirect=/index` | `https://hzdyjs.camasort.com/login?redirect=/index` |
|
||
|
||
### 加密配置
|
||
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境默认值 |
|
||
|--------|------|---------------|---------------|
|
||
| `VUE_APP_RSA_PUBLIC_KEY` | RSA公钥 | （见配置文件） | （见配置文件） |
|
||
| `VUE_APP_RSA_PRIVATE_KEY` | RSA私钥 | （见配置文件） | （见配置文件） |
|
||
| `VUE_APP_CLIENT_ID` | 客户端ID | `e5cd7e4891bf95d1d19206ce24a7b32e` | `e5cd7e4891bf95d1d19206ce24a7b32e` |
|
||
| `VUE_APP_TENANT_ID` | 租户ID | `000000` | `000000` |
|
||
| `VUE_APP_ENCRYPT_HEADER` | 加密请求头名称 | `encrypt-key` | `encrypt-key` |
|
||
| `VUE_APP_ENCRYPT_ENABLED` | 是否启用加密 | `false` | `true` |
|
||
|
||
### H5 开发服务器配置
|
||
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境默认值 |
|
||
|--------|------|---------------|---------------|
|
||
| `VUE_APP_H5_DEV_PORT` | H5开发服务器端口 | `8081` | `8081` |
|
||
| `VUE_APP_H5_DEV_PROXY_TARGET` | 代理目标地址 | `http://localhost:8080` | `http://localhost:8080` |
|
||
|
||
### 应用配置
|
||
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境默认值 |
|
||
|--------|------|---------------|---------------|
|
||
| `VUE_APP_TITLE` | 应用标题 | `智慧校园移动端` | `智慧校园移动端` |
|
||
| `VUE_APP_WECHAT_DEBUG` | 微信JS-SDK调试模式 | `true` | `false` |
|
||
|
||
## 🔧 配置优先级
|
||
|
||
环境变量配置的优先级（从高到低）：
|
||
|
||
1. **`.env.local`** - 本地覆盖配置（最高优先级）
|
||
2. **`.env.[mode].local`** - 模式特定的本地配置
|
||
3. **`.env.[mode]`** - 模式特定配置（如 `.env.development`、`.env.production`）
|
||
4. **`.env`** - 默认配置（如果存在）
|
||
5. **代码中的默认值** - 如果环境变量未设置，使用代码中的默认值
|
||
|
||
## 📦 部署前检查清单
|
||
|
||
### 生产环境部署
|
||
|
||
在部署到生产环境前，请检查并修改 `.env.production` 文件中的以下配置：
|
||
|
||
- [ ] **`VUE_APP_API_BASE_URL`** - 修改为生产环境API地址
|
||
- [ ] **`VUE_APP_DEV_SERVER_URL`** - 修改为生产环境API完整地址
|
||
- [ ] **`VUE_APP_FRONTEND_URL`** - 修改为生产环境前端域名
|
||
- [ ] **`VUE_APP_ENCRYPT_ENABLED`** - 确保设置为 `true`（启用加密）
|
||
- [ ] **`VUE_APP_WECHAT_DEBUG`** - 确保设置为 `false`（关闭调试）
|
||
|
||
### 测试环境部署
|
||
|
||
如果需要单独的测试环境，可以创建 `.env.test` 文件：
|
||
|
||
```bash
|
||
# 复制生产环境配置
|
||
cp .env.production .env.test
|
||
|
||
# 修改测试环境特定配置
|
||
# VUE_APP_API_BASE_URL=https://test-api.example.com
|
||
# VUE_APP_FRONTEND_URL=https://test.example.com
|
||
```
|
||
|
||
然后使用 `--mode test` 参数构建：
|
||
|
||
```bash
|
||
npm run build:h5 -- --mode test
|
||
```
|
||
|
||
## 🔍 如何验证配置
|
||
|
||
### 1. 查看当前使用的配置
|
||
|
||
在代码中可以通过以下方式查看配置：
|
||
|
||
```javascript
|
||
import { REQUEST_CONFIG, ENCRYPT_CONFIG } from '@/common/config.js';
|
||
|
||
console.log('请求配置:', REQUEST_CONFIG);
|
||
console.log('加密配置:', ENCRYPT_CONFIG);
|
||
```
|
||
|
||
### 2. 检查环境变量
|
||
|
||
在开发环境中，可以在浏览器控制台查看：
|
||
|
||
```javascript
|
||
// 查看所有以 VUE_APP_ 开头的环境变量
|
||
console.log(process.env);
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **环境变量命名规则**：
|
||
- 必须以 `VUE_APP_` 开头才能在客户端代码中访问
|
||
- 变量名使用大写字母和下划线
|
||
|
||
2. **敏感信息**：
|
||
- RSA私钥等敏感信息虽然可以通过环境变量配置，但建议：
|
||
- 生产环境的私钥不要提交到 Git
|
||
- 使用 CI/CD 系统注入敏感配置
|
||
- 或使用 `.env.local` 文件（已加入 `.gitignore`）
|
||
|
||
3. **配置更新**：
|
||
- 修改 `.env` 文件后，需要**重启开发服务器**才能生效
|
||
- 生产环境构建时，环境变量会被编译到代码中
|
||
|
||
4. **manifest.json 配置**：
|
||
- H5开发服务器配置（端口、代理）可以通过 `vue.config.js` 从环境变量读取
|
||
- `manifest.json` 中的配置作为默认值保留
|
||
|
||
## 📚 相关文件
|
||
|
||
- **配置文件**：
|
||
- `src/common/config.js` - 配置读取和默认值定义
|
||
- `vue.config.js` - H5开发服务器配置
|
||
- `src/manifest.json` - uni-app 应用配置（默认值）
|
||
|
||
- **环境变量文件**：
|
||
- `.env.example` - 配置示例
|
||
- `.env.development` - 开发环境配置
|
||
- `.env.production` - 生产环境配置
|
||
|
||
## 🔗 参考文档
|
||
|
||
- [Vue CLI 环境变量和模式](https://cli.vuejs.org/zh/guide/mode-and-env.html)
|
||
- [uni-app 环境变量](https://uniapp.dcloud.net.cn/tutorial/env.html)
|
||
|