# BearVPN 快速参考

## 🚀 快速开始

### 1. 克隆项目后立即修改
```bash
# 1. 修改应用名称
# 文件: pubspec.yaml
name: your_app_name

# 2. 修改包标识符
# iOS: ios/Base.xcconfig
BASE_BUNDLE_IDENTIFIER=com.yourcompany.yourapp

# macOS: macos/Runner/Configs/AppInfo.xcconfig  
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.yourapp

# Android: android/app/build.gradle
applicationId "com.yourcompany.yourapp"

# 3. 配置签名信息
# 文件: ios_signing_config.sh 和 macos_signing_config.sh
export APPLE_ID="your-apple-id@example.com"
export TEAM_ID="YOUR_TEAM_ID"
```

## 📁 关键文件位置

| 配置项 | 文件位置 | 说明 |
|--------|----------|------|
| 应用名称 | `pubspec.yaml` | 项目基础配置 |
| **API 域名** | `lib/app/common/app_config.dart` | **API 服务器域名** |
| iOS 包名 | `ios/Base.xcconfig` | iOS 包标识符 |
| macOS 包名 | `macos/Runner/Configs/AppInfo.xcconfig` | macOS 包标识符 |
| Android 包名 | `android/app/build.gradle` | Android 应用 ID |
| iOS 签名 | `ios_signing_config.sh` | iOS 签名配置 |
| macOS 签名 | `macos_signing_config.sh` | macOS 签名配置 |
| 多语言 | `assets/translations/` | 翻译文件目录 |
| 应用图标 | `assets/images/logo.svg` | 主 Logo |

## 🔧 常用命令

### Flutter 命令
```bash
# 安装依赖
flutter pub get

# 清理项目
flutter clean

# 构建各平台
flutter build apk          # Android
flutter build ios          # iOS
flutter build macos        # macOS
flutter build windows      # Windows
flutter build web          # Web
```

### 构建脚本
```bash
# iOS 构建
./build_ios.sh

# macOS 构建
./build_macos_simple.sh

# 签名和打包
./sign_and_package.sh

# 公证
./notarize_only.sh
```

## 🎨 图标尺寸

| 平台 | 尺寸 | 位置 |
|------|------|------|
| iOS | 1024x1024 | `ios/Runner/Assets.xcassets/AppIcon.appiconset/` |
| macOS | 1024x1024 | `macos/Runner/Assets.xcassets/AppIcon.appiconset/` |
| Android | 512x512 | `android/app/src/main/res/mipmap-xxxhdpi/` |
| Web | 512x512 | `web/icons/Icon-512.png` |

## 🌍 支持的语言

- 🇨🇳 简体中文 (`strings_zh.i18n.json`)
- 🇹🇼 繁体中文 (`strings_zh_Hant.i18n.json`)
- 🇺🇸 英文 (`strings_en.i18n.json`)
- 🇯🇵 日文 (`strings_ja.i18n.json`)
- 🇪🇸 西班牙文 (`strings_es.i18n.json`)
- 🇷🇺 俄文 (`strings_ru.i18n.json`)
- 🇪🇪 爱沙尼亚文 (`strings_et.i18n.json`)

## ⚠️ 必须修改的占位符

| 占位符 | 说明 | 文件位置 |
|--------|------|----------|
| `apicn.bearvpn.top` | **API 主域名** | `lib/app/common/app_config.dart` |
| `apibear.nsdsox.com` | **API 备用域名** | `lib/app/common/app_config.dart` |
| `xxxxxxxx@example.com` | Apple ID | 所有签名脚本 |
| `xxxxxxxxxxxxxxxx` | App 专用密码 | 所有签名脚本 |
| `XXXXXXXXXX` | Team ID | 所有签名脚本 |
| `Your Company Name` | 公司名称 | 签名配置 |
| `Your Name` | 开发者姓名 | 签名配置 |
| `com.yourcompany.yourapp` | 包标识符 | 所有平台配置 |

## 🌐 域名配置详解

### 修改 API 服务器域名
```dart
// 文件: lib/app/common/app_config.dart
class KRDomain {
  // 1. 修改主域名列表
  static List<String> kr_baseDomains = [
    "your-api-domain.com",        // 替换为您的API域名
    "backup-api-domain.com"       // 备用API域名
  ];
  
  // 2. 修改当前使用的域名
  static String kr_currentDomain = "your-api-domain.com";
  
  // 3. 修改备用域名获取地址（可选）
  static List<String> kr_backupDomainUrls = [
    "https://your-backup-server.com/domains.txt",
    // 添加更多备用地址
  ];
  
  // 4. 修改本地备用域名（可选）
  static List<String> kr_localBackupDomains = [
    "api.yourcompany.com",
    "backup.yourcompany.com",
    // 添加更多本地备用域名
  ];
}
```

### 域名配置说明
- **主域名列表**: 应用会按顺序尝试这些域名
- **当前域名**: 应用启动时使用的默认域名
- **备用域名地址**: 当主域名都不可用时，从这些地址获取新的域名列表
- **本地备用域名**: 最后的兜底方案，当所有其他方式都失败时使用

## 🔐 签名流程

### iOS 签名
1. 修改 `ios_signing_config.sh`
2. 运行 `source ios_signing_config.sh`
3. 运行 `./build_ios.sh`

### macOS 签名
1. 修改 `macos_signing_config.sh`
2. 运行 `source macos_signing_config.sh`
3. 运行 `./sign_and_package.sh`

## 📱 平台支持

| 平台 | 状态 | 构建脚本 |
|------|------|----------|
| iOS | ✅ | `build_ios.sh` |
| macOS | ✅ | `build_macos_simple.sh` |
| Android | ✅ | `flutter build apk` |
| Windows | ✅ | `flutter build windows` |
| Linux | ✅ | `flutter build linux` |
| Web | ✅ | `flutter build web` |

## 🆘 故障排除

### 常见问题
1. **签名失败**: 检查证书是否有效
2. **构建失败**: 运行 `flutter clean && flutter pub get`
3. **公证失败**: 检查 Apple ID 和密码
4. **图标不显示**: 检查图标文件路径和尺寸

### 调试命令
```bash
# 检查连接
./debug_connection.sh

# 测试连接
./test_connection.sh

# 检查公证状态
./check_notarization_status.sh
```

---

**💡 提示**: 修改配置后记得运行 `flutter clean && flutter pub get` 重新构建项目。