kivy/buildozer

Buildozer

镜像概述和主要用途

Buildozer是由Kivy团队管理的开发工具，用于将Python应用转换为适用于多个平台（包括移动设备）的二进制安装包。开发者通过单个buildozer.spec文件描述应用需求和设置（如标题、图标等），Buildozer即可生成Android、iOS、Windows、macOS和/或Linux的安装包。

该工具依赖其姊妹项目https://github.com/kivy/python-for-android/%E5%92%8Chttps://github.com/kivy/kivy-ios/%EF%BC%8C%E7%89%B9%E5%88%AB%E4%BC%98%E5%8C%96%E4%BA%86https://github.com/kivy/kivy%E5%BA%94%E7%94%A8%E7%9A%84%E6%9E%84%E5%BB%BA%E6%B5%81%E7%A8%8B%EF%BC%8C%E4%BD%86%E4%B9%9F%E5%8F%AF%E7%8B%AC%E7%AB%8B%E7%94%A8%E4%BA%8E%E5%85%B6%E4%BB%96GUI%E6%A1%86%E6%9E%B6%E3%80%82%E5%AF%B9%E4%BA%8EAndroid%E5%B9%B3%E5%8F%B0%EF%BC%8CBuildozer%E4%BC%9A%E8%87%AA%E5%8A%A8%E4%B8%8B%E8%BD%BD%E5%B9%B6%E5%87%86%E5%A4%87%E6%9E%84%E5%BB%BA%E4%BE%9D%E8%B5%96%EF%BC%88%E5%A6%82SDK%E5%92%8CNDK%EF%BC%89%E3%80%82

注意：此工具与在线构建服务buildozer.io无关。

核心功能和特性

• 多平台支持：可构建Android、iOS、Windows、macOS、Linux平台的安装包
• 简化配置：通过单个buildozer.spec文件定义应用需求和设置
• 自动依赖管理：自动下载并配置构建依赖（如Android SDK、NDK）
• Docker环境支持：提供Docker镜像，简化跨环境构建流程
• 缓存机制：支持本地缓存SDK/NDK等资源，加速重复构建
• CI/CD集成：可通过GitHub Action实现自动化构建

使用场景和适用范围

• Python应用开发者需要将应用打包为跨平台二进制文件
• 移动应用开发（Android/iOS）需要简化构建流程
• CI/CD环境中实现Python应用的自动化打包
• 快速原型验证和多平台兼容性测试

详细使用方法和配置说明

Docker镜像构建

常规构建

bash
docker build --tag=kivy/buildozer .

macOS平台构建（需指定架构）

bash
docker buildx build --platform=linux/amd64 --tag=kivy/buildozer .

运行容器

基本运行（查看版本）

bash
docker run --interactive --tty --rm \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer --version

带缓存的构建示例

保留下载的SDK和NDK到本地~/.buildozer目录，加速后续构建：

bash
docker run --interactive --tty --rm \
    --volume "$HOME/.buildozer":/home/user/.buildozer \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer android debug

拉取官方镜像

镜像已发布至Docker Hub和GitHub Container Registry，可直接拉取：

bash
# 从Docker Hub拉取
docker pull kivy/buildozer:latest

# 从GitHub Container Registry拉取
docker pull ghcr.io/kivy/buildozer:latest

基本命令示例

查看帮助

bash
docker run --interactive --tty --rm \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer help

初始化配置文件

在当前目录生成buildozer.spec配置文件：

bash
docker run --interactive --tty --rm \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer init

构建Android调试包

bash
docker run --interactive --tty --rm \
    --volume "$HOME/.buildozer":/home/user/.buildozer \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer android debug

清理构建环境

bash
docker run --interactive --tty --rm \
    --volume "$PWD":/home/user/hostcwd \
    kivy/buildozer distclean

配置说明

buildozer.spec配置文件

通过buildozer init生成的配置文件包含应用基本信息（标题、包名等）和构建设置。需根据项目需求编辑该文件，配置项包括：

• 应用信息：title（应用标题）、package.name（包名）、version（版本号）
• 依赖设置：requirements（Python依赖）、android.permissions（Android权限）
• 构建选项：android.sdk（SDK版本）、ios.codesign.allowed（iOS签名设置）

环境变量覆盖配置

可通过环境变量覆盖buildozer.spec中的配置项，格式为$SECTION_TOKEN（将配置项中的点替换为下划线）：

• title → $APP_TITLE
• package.name → $APP_PACKAGE_NAME
• p4a.source_dir → $APP_P4A_SOURCE_DIR

其他信息

许可证

Buildozer采用MIT许可证，由Kivy社区积极开发维护。

官方文档

完整文档请访问：[***]

支持渠道

遇到使用问题可通过Kivy社区支持渠道获取帮助，详情参见https://github.com/kivy/buildozer/blob/master/CONTACT.md%E6%96%87%E6%A1%A3%E3%80%82

GitHub Action集成

可使用https://github.com/ArtemSBulgakov/buildozer-action%E5%AE%9E%E7%8E%B0CI/CD%E8%87%AA%E5%8A%A8%E5%8C%96%E6%9E%84%E5%BB%BA%EF%BC%8C%E8%AF%A6%E8%A7%81https://github.com/ArtemSBulgakov/buildozer-action#full-workflow%E3%80%82