init

client/ENVIRONMENT_CONFIG.md

@@ -0,0 +1,186 @@
+# 多环境配置说明
+
+## 概述
+
+前端应用现在支持多环境后端 API 配置，可以在开发、预发布和生产环境之间切换。
+
+## 环境类型
+
+### 1. 开发环境 (Development)
+- **默认 API 地址**: `http://localhost:8080/api/v1`
+- **Android 模拟器**: `http://10.0.2.2:8080/api/v1`
+- **用途**: 本地开发和测试
+
+### 2. 预发布环境 (Staging)
+- **默认 API 地址**: `http://your-staging-domain.com/api/v1`
+- **用途**: 上线前测试
+
+### 3. 生产环境 (Production)
+- **默认 API 地址**: `http://your-production-domain.com/api/v1`
+- **用途**: 正式上线
+
+## 使用方法
+
+### 方法一：通过命令行参数设置
+
+#### 开发环境
+```bash
+flutter run --dart-define=ENVIRONMENT=development
+```
+
+#### 预发布环境
+```bash
+flutter run --dart-define=ENVIRONMENT=staging
+```
+
+#### 生产环境
+```bash
+flutter run --dart-define=ENVIRONMENT=production
+```
+
+#### 自定义 API 地址
+```bash
+flutter run --dart-define=API_BASE_URL=http://192.168.1.100:8080/api/v1
+```
+
+### 方法二：通过开发者设置页面（推荐开发环境使用）
+
+1. 在应用的设置页面找到"开发者设置"选项
+2. 选择目标环境或输入自定义 API 地址
+3. 保存设置并重启应用
+
+## 构建配置
+
+### Android 构建
+
+#### 开发版本
+```bash
+flutter build apk --dart-define=ENVIRONMENT=development
+```
+
+#### 生产版本
+```bash
+flutter build apk --dart-define=ENVIRONMENT=production --release
+```
+
+### iOS 构建
+
+#### 开发版本
+```bash
+flutter build ios --dart-define=ENVIRONMENT=development
+```
+
+#### 生产版本
+```bash
+flutter build ios --dart-define=ENVIRONMENT=production --release
+```
+
+### Web 构建
+
+#### 开发版本
+```bash
+flutter build web --dart-define=ENVIRONMENT=development
+```
+
+#### 生产版本
+```bash
+flutter build web --dart-define=ENVIRONMENT=production --release
+```
+
+## 配置文件位置
+
+环境配置文件位于：
+```
+lib/core/config/environment.dart
+```
+
+## 自定义环境配置
+
+如需修改环境配置，编辑 `environment.dart` 文件：
+
+```dart
+static const Map<String, String> productionConfig = {
+  'baseUrl': 'http://your-production-domain.com/api/v1',
+  'wsUrl': 'ws://your-production-domain.com/ws',
+};
+```
+
+## 常见场景
+
+### 场景 1: 本地开发（Web）
+- **设备**: 开发电脑浏览器
+- **API 地址**: `http://localhost:8080/api/v1`
+- **运行命令**: `flutter run -d chrome`
+
+### 场景 2: Android 模拟器开发
+- **设备**: Android 模拟器
+- **API 地址**: `http://10.0.2.2:8080/api/v1`
+- **运行命令**: `flutter run -d android`
+- **说明**: 10.0.2.2 是 Android 模拟器访问宿主机 localhost 的特殊地址
+
+### 场景 3: 真机调试
+- **设备**: 手机真机
+- **API 地址**: `http://你的电脑IP:8080/api/v1`
+- **设置方法**: 
+  1. 确保手机和电脑在同一局域网
+  2. 查看电脑 IP 地址（如 192.168.1.100）
+  3. 在开发者设置中输入: `http://192.168.1.100:8080/api/v1`
+  4. 或使用命令: `flutter run --dart-define=API_BASE_URL=http://192.168.1.100:8080/api/v1`
+
+### 场景 4: 生产环境部署
+- **设备**: 正式用户设备
+- **API 地址**: 生产服务器地址
+- **构建命令**: `flutter build apk --dart-define=ENVIRONMENT=production --release`
+
+## 环境检测
+
+在代码中可以使用以下方法检测当前环境：
+
+```dart
+import 'package:your_app/core/config/environment.dart';
+
+// 检查是否为开发环境
+if (EnvironmentConfig.isDevelopment) {
+  print('当前是开发环境');
+}
+
+// 检查是否为生产环境
+if (EnvironmentConfig.isProduction) {
+  print('当前是生产环境');
+}
+
+// 获取当前 API 地址
+String apiUrl = EnvironmentConfig.baseUrl;
+print('API 地址: $apiUrl');
+```
+
+## 注意事项
+
+1. **重启应用**: 修改环境配置后必须重启应用才能生效
+2. **生产环境**: 生产环境配置应该在构建时通过命令行参数指定，不要在代码中硬编码
+3. **安全性**: 不要在代码中提交敏感信息，如生产环境的真实 API 地址
+4. **测试**: 切换环境后应该进行充分测试，确保 API 连接正常
+5. **网络权限**: Android 需要在 `AndroidManifest.xml` 中添加网络权限
+6. **HTTPS**: 生产环境建议使用 HTTPS 协议
+
+## 故障排查
+
+### 问题 1: Android 模拟器无法连接 localhost
+**解决方案**: 使用 `10.0.2.2` 代替 `localhost`
+
+### 问题 2: 真机无法连接开发服务器
+**解决方案**: 
+- 确保手机和电脑在同一网络
+- 检查防火墙设置
+- 使用电脑的局域网 IP 地址
+
+### 问题 3: 环境切换后仍然连接旧地址
+**解决方案**: 完全关闭并重启应用
+
+### 问题 4: iOS 模拟器无法连接
+**解决方案**: iOS 模拟器可以直接使用 `localhost`，无需特殊配置
+
+## 扩展阅读
+
+- [Flutter 环境变量配置](https://flutter.dev/docs/development/tools/sdk/overview#environment-variables)
+- [Dart 编译时常量](https://dart.dev/guides/language/language-tour#const-keyword)