buildozer打包详解：细说那些我踩过的坑

Buildozer 是一款用于将 Python/Kivy 应用打包为 Android APK 的工具，同时也支持其他框架（如 Pywebview）的打包流程。

环境配置（Windows + WSL2）

Windows环境，官方建议在 WSL2 环境下使用 Buildozer，以下是具体步骤：

在 Microsoft Store 中安装 WSL2 与 Ubuntu ，可参考以下教程：超详细 Windows10/Windows11 子系统（WSL2）安装 Ubuntu20.04（带桌面环境）
在 WSL2 中安装 Buildozer 环境：

bash 复制代码

# 安装依赖包
sudo apt update
sudo apt install -y git zip unzip openjdk-17-jdk python3-pip autoconf libtool pkg-config zlib1g-dev libncurses5-dev libncursesw5-dev libtinfo5 cmake libffi-dev libssl-dev automake

# 安装 buildozer
pip3 install --user buildozer

# 将用户目录添加至 PATH 环境变量
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

💡提示：

依赖列表参考自官方文档，不同 Ubuntu 版本可能略有差异：Installation | Buildozer 1.5.1.dev0 documentation
建议使用普通用户执行 pip3 install --user buildozer，避免因 root 权限引发配置文件初始化告警。

可选：创建专用用户

为 Buildozer 项目创建独立用户有助于隔离权限：

bash 复制代码

# 创建用户 builder
sudo useradd -m -s /bin/bash -c "Buildozer专用用户" builder
sudo passwd builder  # 设置密码，例如 build123

# 将项目目录（如 /usr/myapp）所有权赋予 builder
sudo chown -R builder:builder /usr/myapp

# 切换至新用户
su - builder

完成上述配置后，即可开始使用 Buildozer。

快速开始

初始化 Buildozer

在项目根目录执行：

bash 复制代码

buildozer init

该命令会生成 buildozer.spec 配置文件。

配置应用

根据项目需求编辑 buildozer.spec。若使用 Pywebview 框架，可参考官方示例：pywebview/examples/todos/buildozer.spec

构建 APK

bash 复制代码

# 首次构建（下载依赖耗时较长）
buildozer -v android debug

# 后续构建
buildozer android debug

Buildozer 的优势在于构建过程自动化，但调试构建错误往往较为繁琐。

常见构建错误与解决

0. 网络问题

构建过程中可能需要访问 Google 服务，请确保网络通畅。若使用 WSL，建议采用 NAT 模式以便 Windows 与 WSL 间网络互通。

1. Cython (cython) not found

Cython 是编译 Python 扩展模块的必需工具，安装即可：

bash 复制代码

pip3 install --user cython

2. long 类型报错

错误示例如下：

原因：Python 3 移除了 long 类型，相关 Cython 文件需适配为 int。

解决：手动修改构建缓存目录下相关文件中的 long 引用。常见文件路径如下（示例为 armeabi-v7a 架构）：

.buildozer/android/platform/build-arm64-v8a_armeabi-v7a/build/other_builds/pyjnius-sdl2/armeabi-v7a__ndk_target_21/pyjnius/jnius/jnius_utils.pxi
.buildozer/android/platform/build-arm64-v8a_armeabi-v7a/build/other_builds/pyjnius-sdl2/armeabi-v7a__ndk_target_21/pyjnius/jnius/jnius_conversion.pxi
.buildozer/android/platform/build-arm64-v8a_armeabi-v7a/build/other_builds/kivy/armeabi-v7a__ndk_target_21/kivy/kivy/weakproxy.pyx
.buildozer/android/platform/build-arm64-v8a_armeabi-v7a/build/other_builds/kivy/armeabi-v7a__ndk_target_21/kivy/kivy/graphics/opengl.pyx
.buildozer/android/platform/build-arm64-v8a_armeabi-v7a/build/other_builds/kivy/armeabi-v7a__ndk_target_21/kivy/kivy/graphics/context_instructions.pyx

若构建多平台 APK，需在对应架构目录（如 arm64-v8a）下同步修改。

3. SyntaxError: Missing parentheses in call to 'print'

该错误源于 Python 2 与 Python 3 的 print 语法不兼容。

解决：在 buildozer.spec 中配置跳过语法检查，并排除测试目录：

shell 复制代码

[app]
android.skip_check = True
source.exclude_dirs = tests, pyjnius/tests

4. AndroidManifest 标签兼容性错误

解决：注释 buildozer.spec 中的相关主题配置：

shell 复制代码

# android.apptheme = @android:style/Theme.Material.NoActionBar

5. fatal: destination path 'external/jpeg' already exists

重复构建时缓存冲突导致，清理后重新构建即可：

bash 复制代码

buildozer android clean
buildozer android debug

6. Android 版本不匹配

需确保 buildozer.spec 中的 NDK、SDK、API 版本一致。可参考如下配置并咨询文档或 AI 工具进行调整：

shell 复制代码

android.permissions = INTERNET
android.arch = arm64-v8a, armeabi-v7a
android.ndk = 25
android.sdk = 28
android.minapi = 21
android.api = 29
android.ndk_api = 21

构建成功后的注意事项

即使 APK 打包成功，仍可能因兼容性或代码问题导致闪退。此时可将生成的 Java 代码导入 Android Studio 进一步调试。代码路径通常为：

复制代码

\\wsl.localhost\Ubuntu-22.04\{项目目录}\.buildozer\android\platform\build-arm64-v8a\dists\{项目java代码目录}

结语

最后成功界面示例：

以上是使用 Buildozer 打包 Android APK 过程中的常见问题与解决方案，希望对你有帮助。如果内容对你有用，欢迎点赞、收藏与关注！