# APK 打包方案指南

## ⚠️ 当前状态

检测到你的系统**未安装 Android SDK**，因此无法直接在命令行打包 APK。

---

## 🎯 推荐方案（3选1）

### 方案一：使用 Android Studio（最简单）⭐⭐⭐

这是**最推荐**的方式，Android Studio 会自动处理所有依赖。

#### 步骤：

1. **下载 Android Studio**
   - 官网：https://developer.android.com/studio
   - 国内镜像：https://www.androiddevtools.cn/

2. **安装 Android Studio**
   - 运行安装程序
   - 选择默认选项即可
   - 会自动下载 Android SDK 和必要组件

3. **打开项目**
   ```bash
   # 在项目根目录运行
   npx cap open android
   ```
   或在 Android Studio 中选择：**File → Open → 选择 `android` 文件夹**

4. **等待同步完成**
   - 首次打开需要下载 Gradle（约 100MB）
   - 同步完成后会显示项目结构

5. **构建 APK**
   - 菜单：**Build → Build Bundle(s) / APK(s) → Build APK(s)**
   - 等待构建完成（约 2-5 分钟）

6. **找到 APK**
   - 位置：`android\app\build\outputs\apk\debug\app-debug.apk`
   - 可以直接安装到手机

#### 优点：
- ✅ 全自动，无需配置
- ✅ 图形界面，操作简单
- ✅ 支持真机调试
- ✅ 可以查看日志和错误

#### 缺点：
- ⏰ 首次安装需要时间（约 2-3GB）
- ⏰ 首次构建需要下载依赖

---

### 方案二：手动安装 Android SDK（适合开发者）⭐⭐

如果你已经有 Android Studio 或想单独安装 SDK。

#### 步骤：

1. **下载 Command Line Tools**
   - 地址：https://developer.android.com/studio#command-tools
   - 下载 `commandlinetools-win-*.zip`

2. **解压并设置环境变量**
   ```powershell
   # 创建目录
   mkdir C:\Android\Sdk
   
   # 解压 commandlinetools 到 C:\Android\Sdk\cmdline-tools
   
   # 设置环境变量
   $env:ANDROID_HOME = "C:\Android\Sdk"
   $env:PATH += ";C:\Android\Sdk\cmdline-tools\latest\bin"
   $env:PATH += ";C:\Android\Sdk\platform-tools"
   ```

3. **安装必要的组件**
   ```bash
   # 接受许可证
   sdkmanager --licenses
   
   # 安装必要组件
   sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
   ```

4. **配置 local.properties**
   
   在 `android/local.properties` 中添加：
   ```properties
   sdk.dir=C\:\\Android\\Sdk
   ```

5. **打包 APK**
   ```bash
   cd android
   .\gradlew assembleDebug
   ```

#### 优点：
- ✅ 轻量级，不需要完整 IDE
- ✅ 可以命令行操作
- ✅ 适合 CI/CD

#### 缺点：
- ⚙️ 配置较复杂
- ⚙️ 需要手动管理 SDK

---

### 方案三：使用在线打包服务（最快）⭐

如果只是想快速测试，可以使用在线服务。

#### 推荐服务：

1. **VoltBuilder** (付费)
   - 网址：https://volt.build/
   - 上传 Web 资源，自动打包

2. **Monaca** (免费/付费)
   - 网址：https://monaca.io/
   - 云端构建 Cordova/Capacitor 应用

3. **PhoneGap Build** (已停止服务)
   - 不推荐使用

#### 步骤（以 VoltBuilder 为例）：

1. 注册账号
2. 上传 `dist` 文件夹的内容
3. 配置 APP 信息
4. 点击构建
5. 下载 APK

#### 优点：
- ⚡ 无需安装任何工具
- ⚡ 快速得到 APK

#### 缺点：
- 💰 通常需要付费
- 🔒 代码需要上传到云端
- ⚙️ 自定义程度低

---

## 🚀 快速开始（推荐方案一）

### 一键操作流程：

```bash
# 1. 确保已构建最新代码
npm run build

# 2. 同步到 Android
npx cap sync android

# 3. 打开 Android Studio
npx cap open android
```

然后在 Android Studio 中：
1. 等待 Gradle 同步完成（底部有进度条）
2. 点击菜单：**Build → Build APK(s)**
3. 等待构建完成
4. 点击提示中的 **locate** 按钮找到 APK
5. 将 APK 传输到手机安装

---

## 📱 安装 APK 到手机

### 方法一：USB 传输
1. 手机连接电脑
2. 复制 APK 到手机
3. 在手机文件管理器中找到 APK
4. 点击安装（需要允许"未知来源"）

### 方法二：二维码扫描
1. 在电脑上启动 HTTP 服务器：
   ```bash
   # 在 APK 所在目录
   python -m http.server 8080
   ```
2. 手机浏览器访问：`http://电脑IP:8080/app-debug.apk`
3. 下载并安装

### 方法三：ADB 安装（需要 USB 调试）
```bash
adb install android/app/build/outputs/apk/debug/app-debug.apk
```

---

## 🔧 常见问题

### Q1: Android Studio 打开后一直同步怎么办？
**A**: 
- 检查网络连接
- 配置国内镜像（见下方）
- 耐心等待首次同步（可能需要 10-20 分钟）

### Q2: Gradle 下载太慢怎么办？
**A**: 配置国内镜像

编辑 `android/build.gradle`，在 `buildscript` 和 `allprojects` 的 `repositories` 中添加：
```gradle
maven { url 'https://maven.aliyun.com/repository/google' }
maven { url 'https://maven.aliyun.com/repository/jcenter' }
maven { url 'https://maven.aliyun.com/nexus/content/groups/public' }
```

编辑 `android/gradle/wrapper/gradle-wrapper.properties`：
```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
# 改为国内镜像
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.14.3-all.zip
```

### Q3: 构建失败怎么办？
**A**:
1. 查看错误信息
2. 清理项目：**Build → Clean Project**
3. 重新构建：**Build → Rebuild Project**
4. 检查 Java 版本（需要 JDK 11+）

### Q4: APK 安装后白屏怎么办？
**A**:
1. 检查后端服务是否启动
2. 检查 API 地址配置
3. 使用 Chrome 远程调试查看错误
4. 查看 Logcat 日志

---

## 📊 预期结果

### 构建时间：
- 首次构建：10-20 分钟（下载依赖）
- 后续构建：2-5 分钟

### APK 大小：
- Debug 版本：5-8 MB
- Release 版本：3-5 MB

### APK 位置：
```
android/app/build/outputs/apk/debug/app-debug.apk
```

---

## 💡 建议

**对于初次打包**：
1. ✅ 使用 **方案一（Android Studio）**
2. ✅ 耐心等待首次同步
3. ✅ 配置国内镜像加速
4. ✅ 构建成功后再考虑优化

**对于经常打包**：
1. ✅ 配置 Gradle 缓存
2. ✅ 使用增量构建
3. ✅ 考虑配置 CI/CD

---

## 🎯 下一步

1. **下载安装 Android Studio**
   - https://developer.android.com/studio

2. **运行打包命令**
   ```bash
   npm run build
   npx cap sync android
   npx cap open android
   ```

3. **在 Android Studio 中构建 APK**

4. **安装到手机测试**

如有问题，请查看错误信息并参考上方的"常见问题"部分。