Chaquopy 当前仅官方支持 OpenCV（opencv-python）在 Python 3.8 环境下运行；若项目使用 3.11 等高版本 Python，将因缺少 OpenCV 配置文件 config.py 而抛出 ImportError，需降级 Python 版本并调整构建配置。
chaquopy 当前仅官方支持 opencv（opencv-python）在 python 3.8 环境下运行；若项目使用 3.11 等高版本 python，将因缺少 opencv 配置文件 `config.py` 而抛出 `importerror`，需降级 python 版本并调整构建配置。
在 Android Studio 中通过 Chaquopy 集成 OpenCV 是常见需求，但开发者常遇到如下运行时异常：
Caused by: com.chaquo.python.PyException: ImportError: OpenCV loader: missing configuration file: ['config.py']. Check OpenCV installation
该错误并非 OpenCV 安装不完整或路径错误，而是 Chaquopy 官方预编译的 opencv-python wheel 仅适配 Python 3.8（截至 Chaquopy 14.0）。当 build.gradle 中指定 python { version "3.11" } 时，Chaquopy 会尝试从 PyPI 下载通用 wheel，但其内置的 OpenCV 加载器依赖特定于 3.8 的编译配置（如 config.py），导致初始化失败。
✅ 正确配置步骤
-
统一 Python 版本为 3.8
修改 app/build.gradle 中的 python 块，移除重复声明（原配置中 python{} 出现三次，属语法错误），仅保留一组完整配置：
python {
version "3.8" // 必须为 3.8 —— 唯一受支持版本
buildPython "C:/Python38/python.exe" // 若本地有 Python 3.8，可指定路径（非必需）
pip {
install "numpy"
install "opencv-python==4.9.0.80" // 推荐锁定兼容版本（对应 Python 3.8）
}
}
sourceSets {
main {
python.srcDir "src/main/python"
}
}⚠️ 注意：buildPython 仅用于构建期（如 Cython 扩展编译），Chaquopy 运行时使用内置解释器，因此该路径无需严格匹配设备环境，但必须确保本地能访问对应 Python 3.8 解释器以完成 pip 安装。
-
验证 Python 模块导入逻辑
在 MainActivity.kt 中，建议增加异常捕获与日志输出，便于调试：
val py = Python.getInstance()
try {
val module = py.getModule("script")
Log.i("Chaquo", "Script loaded successfully")
} catch (e: RuntimeException) {
Log.e("Chaquo", "Failed to load script", e)
}-
Python 脚本保持简洁（无需额外配置）
src/main/python/script.py 可直接使用标准导入：
import numpy as np import cv2 # ✅ 在 Python 3.8 + Chaquopy 下可正常加载 text = "ABC" num = 55 # 示例：验证 OpenCV 功能（可选） # print(cv2.__version__) # 输出如 '4.9.0'
? 关键注意事项
- ❌ 不要使用 python { version "3.9+" } + opencv-python：即使 pip 安装成功，运行时仍会触发 config.py 缺失错误；
- ✅ Chaquopy 团队已将 Python 3.9+ 的 OpenCV 支持列为 GitHub Issue #779，建议订阅以获取更新通知；
- ? 若需更高版本 OpenCV 功能（如 DNN 模块），可考虑手动编译 ARM64/aarch64 兼容的 wheel 并通过 pip { install "file://..." } 引入，但需自行维护 ABI 兼容性；
- ? 测试时请彻底清理构建缓存：执行 ./gradlew clean + 删除 app/.cxx/ 和 app/build/ 目录，避免旧版本残留干扰。
遵循上述配置后，OpenCV 将正常初始化，cv2 模块可安全用于图像读取、处理等操作，为移动端 Python 计算机视觉应用提供稳定基础。
