Kivy+Buildozer 打包 APK 踩坑：python-for-android 克隆失败

目录

一、问题现象

二、前置清理操作

三、核心解决方案（亲测有效）

[方案 1：国内镜像克隆 + 强制指定本地路径（推荐）](#方案 1：国内镜像克隆 + 强制指定本地路径（推荐）)

[方案 2：命令行直接指定本地路径（快速应急）](#方案 2：命令行直接指定本地路径（快速应急）)

[方案 3：手动下载源码包（无 Git 环境备用）](#方案 3：手动下载源码包（无 Git 环境备用）)

[四、Ubuntu 虚拟环境常用操作](#四、Ubuntu 虚拟环境常用操作)

五、问题根因分析

六、总结与避坑要点

七、写在最后

---

论文投稿：
2026年决策、管理与学习系统国际学术会议

大会官网：https://ais.cn/u/yY3EZf

大会时间：2026年4月10-12日

大会地点：马来西亚-吉隆坡

一、问题现象

在 Ubuntu 虚拟机中执行buildozer android debug deploy run打包 Kivy 项目时，出现Git 克隆超时 / 无法连接错误：

fatal: 无法访问 'https://hub.fastgit.xyz/kivy/python-for-android.git/'：
Failed to connect to hub.fastgit.xyz port 443 after 21066 ms: Couldn't connect to server

即便手动用 Gitee 镜像克隆成功，Buildozer 仍会判定为非官方仓库并删除重建，再次触发网络失败，陷入死循环。

二、前置清理操作

先清理旧缓存与平台文件，避免残留文件干扰：

# 清理python-for-android目录
sudo rm -rf /home/xh/my-kivy-app/.buildozer/android/platform/python-for-android
# 清理buildozer全局缓存
sudo rm -rf ~/.buildozer/cache

三、核心解决方案（亲测有效）

方案 1：国内镜像克隆 + 强制指定本地路径（推荐）

1. 进入平台目录并克隆 Gitee 镜像

mkdir -p /home/xh/my-kivy-app/.buildozer/android/platform/
cd /home/xh/my-kivy-app/.buildozer/android/platform/
git clone https://gitee.com/mirrors/python-for-android.git
cd python-for-android
git checkout master

1. 修改buildozer.spec强制使用本地仓库打开配置文件，在末尾添加：

   强制使用本地python-for-android，跳过官方仓库校验

   p4a.local_recipes = /home/xh/my-kivy-app/.buildozer/android/platform/python-for-android
   p4a.source_dir = /home/xh/my-kivy-app/.buildozer/android/platform/python-for-android

2. 重新执行打包命令

cd /home/xh/my-kivy-app
buildozer android debug deploy run

方案 2：命令行直接指定本地路径（快速应急）

无需改配置，直接带参数运行：

buildozer android debug deploy run --p4a-dir=/home/xh/my-kivy-app/.buildozer/android/platform/python-for-android

方案 3：手动下载源码包（无 Git 环境备用）

cd /home/xh/my-kivy-app/.buildozer/android/platform/
wget https://github.com/kivy/python-for-android/archive/refs/heads/master.zip -O p4a.zip
unzip p4a.zip
mv python-for-android-master python-for-android
rm p4a.zip

四、Ubuntu 虚拟环境常用操作

打包过程中常用环境命令，避免误操作：

# 退出Python虚拟环境
deactivate

# 重新进入虚拟环境
source kivy_venv/bin/activate

五、问题根因分析

1. 网络限制：国内网络无法稳定访问 GitHub 与 fastgit 镜像，导致克隆超时。
2. Buildozer 校验机制：会检查仓库源地址与分支，非官方 GitHub 源会被自动删除重建。
3. 缓存残留：旧的平台文件与缓存会引发路径冲突，必须先清理。

六、总结与避坑要点

1. 打包前务必清理缓存，减少未知报错。
2. 网络不佳时优先使用Gitee 镜像，不要依赖默认源。
3. 关键是强制指定本地 p4a 路径，跳过 Buildozer 的仓库校验逻辑。
4. 虚拟环境切换用deactivate，不要直接关闭终端。

七、写在最后

这次在 Ubuntu 下用 Buildozer 给 Kivy 应用打包 Android APK，全程踩了不少环境权限、网络克隆、仓库校验的坑。从最开始的 externally-managed-environment 虚拟环境问题，到后来 python-for-android 克隆失败、Buildozer 强制删仓库重下，一步步排查下来，其实核心就两点：

• 国内网络环境下，一定要用 Gitee 镜像替代 GitHub；
• 不想被 Buildozer 反复校验折腾，就强制指定本地 p4a 路径，跳过官方源检查。

整个过程虽然繁琐，但也算完整走通了一套 Kivy 从开发到 Android 打包的流程。如果你也在做 Kivy 跨平台开发，或者同样卡在打包这一步，欢迎在评论区交流报错信息、配置细节，我会尽量回复～也欢迎点赞、收藏本文，后续会继续更新 Kivy 开发与打包相关的实战踩坑笔记！