Kivy 项目导出 APK 常见 Pyjnius 编译错误解决方案

引言

Kivy 是一个强大的 Python 框架，用于快速开发跨平台应用程序，尤其是图形用户界面（GUI）。通过 Buildozer 工具，Kivy 开发者可以方便地将 Python 应用程序打包成 Android 平台的 APK 文件。然而，在打包过程中，开发者可能会遇到各种编译错误，其中 pyjnius 相关的 clang 错误是较为常见且棘手的问题，尤其是在处理 Python C 扩展时。本文将深入分析这类错误，并提供一套系统的解决方案。

错误分析：深入理解 Pyjnius 编译失败

在 Kivy 项目导出 APK 的过程中，当执行 buildozer -v android debug 命令时，如果遇到类似于以下日志中的 clang 错误，通常意味着 pyjnius 库在 Android 目标环境下的编译遇到了问题：

clang-14: error: no such file or directory: 'jnius/jnius.c'
error: command '/home/abr/.buildozer/android/platform/android-ndk-r25b/toolchains/llvm/prebuilt/linux-x86_64/bin/clang' failed with exit code 1

和更关键的：

jnius/jnius.c:54433:5: error: expression is not assignable
    ++Py_REFCNT(o);
    ^ ~~~~~~~~~~~~

这些错误信息揭示了几个关键问题点：

1. 拼写错误：首先，需要检查执行命令时是否存在拼写错误。例如，将 buildozer 误写为 biuldozer 将直接导致命令无法识别，从而中断整个打包流程。
2. jnius/jnius.c 文件缺失：pyjnius 是 Kivy 在 Android 上与 Java 代码交互的关键库。它是一个 Python C 扩展，需要通过 Cython 将 .pyx 源文件转换为 .c 文件，然后使用 Android NDK 中的 clang 编译器进行编译。首次构建 pyjnius 时，jnius.c 文件可能尚未生成，导致第一次编译失败是预期行为。但如果 Cython 化之后仍然找不到或编译失败，则表明 Cython 转换或后续 C 编译过程存在问题。
3. expression is not assignable 错误 (++Py_REFCNT(o);)：这是最核心的编译错误。Py_REFCNT 是 Python 对象引用计数的宏。在 Python 3.9 及更高版本中，为了防止不安全的直接内存操作，PyObject 结构中的 ob_refcnt 字段被标记为只读，不再允许通过 ++ 或 -- 等操作符直接修改。取而代之的是 Py_INCREF() 和 Py_DECREF() 等函数。 当 pyjnius 的 C 代码（通常由 Cython 从 .pyx 文件生成）试图直接修改 Py_REFCNT 时，如果 Buildozer 内部为 Android 目标环境配置的 Python 版本（或其 C API 头文件）的行为类似于 Python 3.9+，即使本地系统 Python 版本是 3.8.10，也会触发此 "expression is not assignable" 错误。这通常意味着 pyjnius 的版本与 Buildozer 正在使用的 Android 目标 Python 版本或 NDK/Clang 版本之间存在兼容性问题。

解决方案与最佳实践

解决这类问题需要系统性地检查 Buildozer 配置和环境。

步骤一：检查并纠正 Buildozer 命令

确保您使用的 Buildozer 命令拼写正确无误。 错误示例：

biuldozer -v android debug

正确命令：

buildozer -v android debug

这是一个基础但经常被忽视的错误点。

先见AI

数据为基，先见未见

95

查看详情

步骤二：审查 buildozer.spec 配置文件

buildozer.spec 文件是 Buildozer 的核心配置文件，它定义了应用程序的元数据、依赖项、Android 工具链版本等。

1. 核心：requirements 部分 此部分列出了您的 Kivy 应用及其依赖库。确保所有必要的依赖都已列出，并且版本兼容。pyjnius 是其中的关键。

   [app]
   # ... 其他应用设置 ...
   requirements = python3,kivy,pyjnius,hostpython3,sdl2,setuptools,cython
   # 如果遇到 Pyjnius 编译问题，可以尝试指定一个已知兼容的版本
   # requirements = python3,kivy,pyjnius==1.4.0,hostpython3,sdl2,setuptools,cython
   # ...

   登录后复制
   • python3: 指定使用 Python 3。
   • kivy: 您的 Kivy 应用本身。
   • pyjnius: Kivy 与 Android Java API 交互的桥梁。其版本兼容性至关重要。
   • hostpython3: 在构建主机上运行的 Python，用于执行构建脚本。
   • sdl2: Kivy 在 Android 上使用的图形后端。
   • setuptools, cython: 构建 Python C 扩展所需的工具。

2. NDK/SDK 版本配置 Buildozer 使用 Android NDK (Native Development Kit) 和 SDK (Software Development Kit) 来编译原生代码和构建 APK。不兼容的 NDK/SDK 版本可能导致编译错误。

   [buildozer]
   # ...
   # Android 工具链版本配置
   android.ndk = 25b # 推荐尝试 NDK 25b 或 23b，避免使用最新的 NDK 版本可能带来的兼容性问题
   android.sdk = 29  # 根据目标 Android 版本设置 SDK API 级别
   android.api = 29  # 目标 API 级别
   android.minapi = 21 # 最小支持 API 级别

   登录后复制
   • android.ndk: 针对 Py_REFCNT 错误，有时较新的 NDK 版本会引入更严格的 C/C++ 标准或与旧版 pyjnius 不兼容的头文件。尝试指定一个较旧但稳定的 NDK 版本（例如 23b 或 21b）可能会解决问题。NDK 25b 是一个相对稳定的版本，但如果问题依旧，可以尝试更早的版本。
   • android.sdk / android.api: 这些设置定义了 Buildozer 下载和使用的 Android SDK 版本以及您的应用的目标 API 级别。确保它们与您的应用需求和 Buildozer 的兼容性列表相符。

步骤三：清理 Buildozer 缓存

在修改 buildozer.spec 或尝试不同解决方案后，务必清理 Buildozer 的构建缓存，以确保所有更改都能生效，并强制 Buildozer 重新下载或编译依赖项。

buildozer -v android clean

执行此命令后，再次尝试打包：

buildozer -v android debug

步骤四：环境兼容性与依赖项管理

1. Python 版本与 C API 兼容性 虽然 Buildozer 会为 Android 目标环境管理一个独立的 Python 环境，但本地系统上的 Cython 版本也可能影响生成的 C 代码。Py_REFCNT 错误通常指向 pyjnius 的 C 代码与目标 Python C API 之间存在不兼容。确保您没有手动覆盖 Buildozer 内部的 Python 版本。 如果指定了特定版本的 pyjnius 仍然失败，可以尝试在 buildozer.spec 中添加 android.python_version = 3.8 (或 Buildozer 支持的其他版本) 来明确目标 Python 版本，但这通常不是必需的，Buildozer 会根据 requirements 自动处理。

2. Cython 版本pyjnius 依赖 Cython 将 .pyx 文件转换为 .c 文件。如果 Buildozer 使用的 Cython 版本过旧或过新，可能导致生成的 .c 文件不兼容目标 Python 环境。Buildozer 通常会自行管理 Cython，但如果怀疑是此问题，可以尝试：

   • 确保 requirements 中包含 cython。
   • 更新 Buildozer 本身（见下一步）。

高级故障排除建议

如果上述步骤未能解决问题，可以考虑以下高级建议：

• 更新 Buildozer：确保您使用的 Buildozer 版本是最新的稳定版。新版本通常会修复旧版本存在的兼容性问题。

  pip install --upgrade buildozer

  登录后复制
• 详细日志分析：在 buildozer -v android debug 命令中，-v 参数提供了详细的日志输出。仔细阅读日志，特别是 [DEBUG] 和 [ERROR] 行附近的输出，可能会发现更具体的错误信息或线索。
• 手动检查 Buildozer 目录：导航到 Buildozer 的构建目录（通常在项目根目录下的 .buildozer/android/platform/），检查 pyjnius 相关的构建产物。例如，查看 jnius/jnius.c 文件是否存在，以及其内容是否与预期的 Python C API 兼容。

注意事项

• 跨平台编译的复杂性：将 Python 应用打包到 Android 涉及多个工具链和环境的协调，出现问题是常态。
• 耐心与迭代尝试：解决这类问题通常需要多次尝试和调整配置。每次更改后，记得执行 buildozer -v android clean。
• 社区资源：如果问题依然无法解决，查阅 Kivy 和 Buildozer 的官方文档、GitHub Issue 页面或相关社区论坛，可能会找到类似的案例和解决方案。

总结

Kivy 项目导出 APK 时遇到的 pyjnius 编译错误，特别是 clang 报告的 expression is not assignable，通常源于 Buildozer 配置、依赖项版本不匹配或 Android 工具链兼容性问题。通过仔细检查 buildozer.spec 文件中的 requirements 和 Android NDK/SDK 配置，纠正命令拼写错误，并进行彻底的缓存清理，大多数这类问题都能得到有效解决。理解错误背后的技术原理，结合系统的故障排除方法，是确保 Kivy 应用顺利部署到 Android 平台的关键。

以上就是Kivy 项目导出 APK 常见 Pyjnius 编译错误解决方案的详细内容，更多请关注php中文网其它相关文章！