Android APK 构建指南¶

📦 已完成的工作¶

我已经在项目中配置好了 Capacitor，现在你只需要：

在本地电脑上安装必要软件
运行一个命令
获得 APK 文件

🖥️ 准备工作（只需做一次）¶

第一步：安装 Android Studio¶

访问 https://developer.android.com/studio/
下载并安装 Android Studio
安装时选择「Standard」安装类型
安装完成后，打开 Android Studio，它会自动下载 SDK

第二步：配置环境变量¶

macOS / Linux¶

在终端运行：

# 添加到 ~/.zshrc 或 ~/.bash_profile
echo 'export ANDROID_HOME=~/Library/Android/sdk' >> ~/.zshrc
echo 'export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin' >> ~/.zshrc
source ~/.zshrc

Windows¶

右键「此电脑」→ 属性 → 高级系统设置
点击「环境变量」
在「系统变量」中新建：
变量名：ANDROID_HOME
变量值：C:\Users\你的用户名\AppData\Local\Android\Sdk

第三步：接受 License¶

# macOS/Linux
yes | ~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager --licenses

# Windows (在 Android Studio 的 bin 目录运行)
sdkmanager --licenses

🚀 一键构建 APK¶

方法一：使用脚本（推荐）¶

# 1. 进入项目目录
cd NiuMaBaiShen-web

# 2. 给脚本添加执行权限
chmod +x android/build-apk.sh

# 3. 运行脚本
./android/build-apk.sh

方法二：手动命令¶

# 1. 进入 Android 目录
cd android

# 2. 给 Gradle 脚本添加执行权限
chmod +x gradlew

# 3. 构建 Debug APK
./gradlew assembleDebug

# 4. APK 会在这个位置
# android/app/build/outputs/apk/debug/app-debug.apk

📱 安装 APK 到手机¶

方法一：数据线传输¶

用数据线连接手机和电脑
手机开启「开发者模式」和「USB 调试」
复制 APK 文件到手机
在手机上点击安装

方法二：扫码安装¶

安装一个「airdroid」或「Send Anywhere」等传输软件
在电脑上打开 APK 的二维码
手机扫码下载安装

⚠️ 常见问题¶

1. 「ANDROID_HOME 没有设置」¶

# macOS
export ANDROID_HOME=~/Library/Android/sdk

# Linux
export ANDROID_HOME=~/Android/Sdk

# Windows
set ANDROID_HOME=C:\Users\你的用户名\AppData\Local\Android\Sdk

2. 「Java 版本不对」¶

需要 Java 11 或 17：

# macOS (使用 Homebrew)
brew install openjdk@17
export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"

# Ubuntu/Debian
sudo apt install openjdk-17-jdk

3. Gradle 构建失败¶

cd android
./gradlew clean
./gradlew assembleDebug --info  # 查看详细错误

4. 手机无法安装¶

检查手机系统版本（需要 Android 5.0+）
开启手机「安装未知来源应用」权限
检查 APK 是否有签名

🎯 构建类型说明¶

类型	用途	文件位置
Debug	测试用，可以直接安装	`app/build/outputs/apk/debug/`
Release	上架应用商店用，需要签名	`app/build/outputs/apk/release/`

📋 构建成功后¶

你会获得一个文件： - NiuMaBaiShen-web/android/app/build/outputs/apk/debug/app-debug.apk

这个 APK： - ✅ 可以安装到任何 Android 手机测试 - ✅ 功能完整 - ⚠️ Debug 签名，应用商店不接受 - ⚠️ 需要用「发布签名」才能上架

🔐 生成发布签名（上架用）¶

# 生成签名密钥
keytool -genkey -v -keystore niumabaishen.jks -keyalg RSA -keysize 2048 -validity 10000 -alias niumabaishen

# 用签名构建 Release APK
./gradlew assembleRelease

🆘 需要帮助？¶

如果遇到问题，告诉我错误信息，我来帮你解决！

📁 当前项目结构¶

NiuMaBaiShen-web/
├── app/                 # Next.js 前端代码
├── components/          # React 组件
├── lib/                # API 和状态管理
├── android/            # Android 项目（刚生成的）
│   ├── app/
│   │   └── build/outputs/apk/  # APK 输出位置
│   └── build-apk.sh    # 一键构建脚本
├── dist/               # 构建后的静态文件
├── capacitor.config.ts # Capacitor 配置
└── package.json

构建成功后，把 APK 文件发给我，我可以帮你： 1. 验证功能是否正常 2. 生成二维码方便分发 3. 准备上架资料