hzdyjs/mobile/README-ENV.md

移动端环境变量配置说明

📋 概述

移动端工程已支持通过 .env 文件进行环境配置管理，方便在不同环境（开发、测试、生产）之间切换配置，无需修改代码。

📁 环境变量文件

项目包含以下环境变量文件：

• .env.example - 环境变量配置示例文件（应提交到 Git）
• .env.development - 开发环境配置（应提交到 Git）
• .env.production - 生产环境配置（应提交到 Git）
• .env.local - 本地覆盖配置（不应提交到 Git，已在 .gitignore 中忽略）

🚀 快速开始

1. 使用默认配置

项目已包含开发和生产环境的默认配置，可以直接使用：

# 开发环境（自动使用 .env.development）
npm run dev:h5

# 生产环境构建（自动使用 .env.production）
npm run build:h5

2. 自定义本地配置

如果需要覆盖某些配置，可以创建 .env.local 文件：

# 复制示例文件
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 文件：

# 复制生产环境配置
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 参数构建：

npm run build:h5 -- --mode test

🔍 如何验证配置

1. 查看当前使用的配置

在代码中可以通过以下方式查看配置：

import { REQUEST_CONFIG, ENCRYPT_CONFIG } from '@/common/config.js';

console.log('请求配置:', REQUEST_CONFIG);
console.log('加密配置:', ENCRYPT_CONFIG);

2. 检查环境变量

在开发环境中，可以在浏览器控制台查看：

// 查看所有以 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 环境变量和模式
• uni-app 环境变量