kivy + buildozer 是将 python 项目打包为 android apk 的主流稳定方案，适用于 gui 类应用，需在 linux/macos 或 windows 的 wsl2 中运行，要求标准 kivy 项目结构、正确配置 buildozer.spec，并支持调试与签名构建。
把 Python 项目打包成 Android APK，主流且稳定的方式是用 Kivy + Buildozer。它不是“一键转译”，而是将 Python 代码嵌入到原生 Android 容器中运行，适合 GUI 应用（如工具类、小游戏、数据展示类 App）。纯命令行或后台服务类程序不适用此方案。
前提：只支持 Linux/macOS，Windows 需用 WSL
Buildozer 官方不支持 Windows 原生环境。如果你用 Windows，必须启用 WSL2（推荐 Ubuntu 22.04），并在其中完成全部操作。macOS 用户需装 Xcode 命令行工具和 JDK 17；Linux 用户需确保系统依赖完整（如 python3-dev、build-essential、cython 等）。
核心步骤：Kivy 项目结构 + buildozer.spec 配置
你的项目要符合 Kivy 的标准结构：
- 根目录下有 main.py（必须，是启动入口）
- 资源文件（图片、字体、配置等）放在 assets/ 或同级目录，后续在 buildozer.spec 中声明
- 第三方 Python 包写在 requirements = kivy,requests,numpy（注意：不是所有 PyPI 包都支持 Android，比如含 C 扩展又没提供 aarch64 轮子的包会编译失败）
运行 buildozer init 生成 buildozer.spec，重点修改以下字段：
立即学习“Python免费学习笔记（深入）”；
- title = YourApp（App 名称）
- package.name = yourapp（小写字母+数字，唯一标识）
- package.domain = org.example（反向域名格式）
- requirements = python3,kivy,xxx（python3 必须显式写上）
- android.permissions = INTERNET,WRITE_EXTERNAL_STORAGE（按需申请权限）
- source.include_exts = py,png,jpg,kv,ttf（告诉 buildozer 哪些后缀文件要打进 APK）
构建与调试：从命令到 APK
在项目根目录执行：
- buildozer android debug → 编译生成 bin/yourapp-x.x-debug.apk（带调试信息，可连 logcat）
- buildozer android release → 生成未签名 APK，还需用 buildozer android apk --sign 签名才能安装到真机
首次构建耗时很长（可能 20–60 分钟），因为要下载 Android SDK/NDK、编译 Python 和 Kivy 依赖。建议保持网络畅通，避免中断。出错时优先看最后 20 行日志，常见问题包括：JDK 版本不对、$ANDROID_SDK_ROOT 路径未设、requirements 里用了不兼容包（如 pandas、scikit-learn）、kv 文件路径写错。
替代方案说明（不推荐新手）
BeeWare (Toga) 支持 Python 写原生 UI，但 Android 支持仍不稳定，文档少，社区案例有限；Chaquopy 是让 Java/Kotlin 工程调用 Python，适合已有 Android 项目加 Python 模块，不适合纯 Python 启动；Nuitka + JNI 属于高阶定制，工程量大，无成熟模板。对绝大多数想快速出 APK 的 Python 开发者，Kivy + Buildozer 仍是当前最可行的路径。
