📱 使用 Kivy 将 Python 应用打包成 Android APK 完整指南

1 环境准备与安装

1.1 系统要求

推荐操作系统：Ubuntu 20.04 或更高版本（在 Linux 环境下最为稳定）
Windows 用户：建议使用 WSL（Windows Subsystem for Linux）或虚拟机
Python 版本：Python 3.8 或更高版本

1.2 安装必要依赖

在 Ubuntu/Debian 系统上，打开终端并运行以下命令安装所有必需的依赖：

bash
# 更新系统包管理器
sudo apt update
sudo apt upgrade -y

# 安装编译工具和依赖
sudo apt install -y python3-pip python3-setuptools python3-virtualenv git zip unzip
sudo apt install -y build-essential libffi-dev zlib1g-dev libncursesw5-dev
sudo apt install -y libgdbm-dev libc6-dev zlib1g-dev libsqlite3-dev tk-dev
sudo apt install -y libssl-dev openssl cython libxml2-dev libxslt1-dev

# 安装图形和 OpenGL 相关依赖
sudo apt install -y libgl1-mesa-dev libgles2-mesa-dev

# 安装 Java 开发工具包
sudo apt install -y openjdk-11-jdk

1.3 安装 Kivy 和 Buildozer

bash
# 安装 Kivy
pip3 install kivy

# 安装 Buildozer
pip3 install buildozer

2 创建 Kivy 应用

2.1 简单的示例应用

创建一个项目目录，并在其中创建 main.py 文件：

python
from kivy.app import App
from kivy.uix.button import Button

class MyApp(App):
    def build(self):
        return Button(text='Hello, Kivy!')

if __name__ == '__main__':
    MyApp().run()

2.2 测试应用

在继续之前，先测试你的应用是否能正常运行：

bash
python3 main.py

如果一切正常，你应该能看到一个显示 "Hello, Kivy!" 按钮的窗口。

3 配置 Buildozer

3.1 初始化 Buildozer

在项目目录中运行以下命令：

bash
buildozer init

这会在当前目录生成一个 buildozer.spec 文件，其中包含了所有的构建配置。

3.2 关键配置说明

以下表格列出了 buildozer.spec 文件中需要关注和可能修改的重要配置项：

配置项	描述	示例值
`title`	应用名称	`My Kivy App`
`package.name`	应用包名（全部小写）	`myapp`
`package.domain`	应用域名（组织反域名）	`org.example`
`source.dir`	源代码目录	`.`
`source.include_exts`	包含的文件类型	`py,png,jpg,kv,atlas,txt`
`version`	应用版本号	`0.1`
`requirements`	Python 依赖	`python3,kivy,cython`
`android.permissions`	Android 权限	`INTERNET, WRITE_EXTERNAL_STORAGE`
`presplash.filename`	启动画面图片	`%(source.dir)s/data/presplash.png`
`icon.filename`	应用图标	`%(source.dir)s/data/icon.png`

3.3 常用配置修改

根据你的需求修改 buildozer.spec 文件：

ini
[app]
title = My Kivy App
package.name = myapp
package.domain = org.example
source.dir = .
source.include_exts = py,png,jpg,kv,atlas,txt
version = 0.1
requirements = python3,kivy,cython

[buildozer]
log_level = 2

[app::android]
permissions = INTERNET

[app::android:meta_data]

如果你需要访问网络、存储等功能，记得在 android.permissions 中添加相应权限。

4 打包 APK

4.1 首次构建

在项目目录中运行以下命令开始构建：

bash
buildozer -v android debug

注意：

第一次构建需要下载 Android SDK、NDK 和其他依赖，可能需要 30-60 分钟，具体取决于你的网络速度
确保网络连接稳定，因为需要从 GitHub 和其他源下载大量文件

4.2 网络问题解决方案

如果在国内或遇到网络问题，可以尝试以下方法：

bash
# 设置 HTTP/HTTPS 代理（根据你的实际情况修改）
export http_proxy=http://127.0.0.1:38457
export https_proxy=http://127.0.0.1:38457

# 或者使用 FastGithub 等加速工具

4.3 构建类型

调试版本：buildozer -v android debug - 包含调试信息，未签名
发布版本：buildozer -v android release - 需要签名，用于上架应用商店

5 定位和获取 APK 文件

构建成功后，APK 文件会生成在 bin 目录中：

调试 APK：bin/MyApp-0.1-debug.apk
发布 APK：bin/MyApp-0.1-release.apk

6 安装和测试

6.1 安装到安卓设备

方法一：使用 ADB 安装

bash
adb install bin/MyApp-0.1-debug.apk

方法二：手动安装

将 APK 文件传输到安卓手机
在手机上启用"未知来源"安装权限
使用文件管理器找到 APK 文件并安装

6.2 查看日志

如果应用运行异常，可以通过以下命令查看日志：

bash
adb logcat | grep python

7 常见问题与解决方案

以下表格汇总了打包过程中可能遇到的常见问题及解决方法：

问题现象	可能原因	解决方案
SSL/SSH 错误	Ubuntu 版本过旧	使用 Ubuntu 18.04 或更高版本
下载过程中失败	网络不稳定	设置代理或使用加速器
文件已存在错误	上次下载不完整	删除 `.buildozer` 文件夹重新下载
提取压缩包失败	下载文件损坏	手动下载并替换对应文件
应用启动崩溃	缺少依赖库	检查 `requirements` 是否包含所有依赖
预加载画面卡住	资源文件问题	检查图标和启动画面文件格式

7.1 清理构建缓存

如果遇到构建问题，可以尝试清理缓存：

bash
# 清理构建文件
buildozer android clean

# 完全清理（包括下载的依赖）
buildozer distclean

7.2 添加缺失的依赖

如果应用使用了其他 Python 库，确保在 buildozer.spec 的 requirements 中添加它们：

ini
requirements = python3,kivy,cython,requests,pillow

8 高级配置

8.1 应用签名（发布版本）

要对发布版 APK 进行签名，首先创建密钥库：

bash
keytool -genkey -v -keystore my-release-key.keystore -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

然后在 buildozer.spec 中配置：

ini
[app]
# 发布构建配置
buildozer.release_keystore = /path/to/my-release-key.keystore
buildozer.release_keystore_password = YOUR_PASSWORD
buildozer.release_key_alias = my-alias
buildozer.release_key_password = YOUR_PASSWORD

8.2 优化 APK 大小

ini
[app]
# 只指定需要的架构
android.arch = armeabi-v7a

# 排除不必要的文件
source.exclude_exts = .pyc,.git,.gitignore

总结

通过以上步骤，应该能够成功将 Kivy 应用打包为 Android APK。关键要点：

环境准备：使用推荐的 Ubuntu 版本可以避免多数问题
网络稳定：首次构建需要下载大量依赖，稳定的网络至关重要
耐心调试：如果遇到问题，查看终端输出日志，通常会有详细的错误信息

如果在具体步骤中遇到问题，可以查阅 Buildozer 官方文档或 Kivy 社区获取更多帮助。