ai_english/client/ENVIRONMENT_CONFIG.md

# 多环境配置说明

## 概述

前端应用现在支持多环境后端 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)