python-for-android 构建选项完全指南：Bootstrap 选择、命令行参数与 APK 体积优化

开发工具构建工具移动开发【免费下载链接】python-for-androidTurn your Python application into an Android APK项目地址https://gitcode.com/gh_mirrors/py/python-for-android点击查看免费下载本篇技术指南以 python-for-android下文简称 p4a官方文档中的构建选项Build options章节为核心系统讲解如何为你的 Python 应用选择不同的 Android 后端Bootstrap、如何精确控制 APK 的版本号、权限、图标、启动画面、屏幕方向等关键属性以及如何通过需求黑名单显著压缩 APK 体积。读完本文你将掌握 p4a 命令行中几乎全部常用构建参数的语义、取值约束与底层实现原理能够独立完成从命令行到可分发 APK 的完整配置。一、Python 版本的选择与历史约束p4a 支持使用 Python 3.8 及更高版本。若要在构建时显式指定 Python 版本可在--requirements中同时锁定运行时与宿主解释器的版本p4a apk --requirementspython33.10.11,hostpython33.10.11 ...其中python3是最终打包进 APK 的运行时解释器hostpython3则是在构建机上运行的宿主解释器用于预编译标准库、生成字节码等。将两者锁定为同一版本可以避免跨版本 ABI 不兼容问题。两个历史约束也值得了解Python 2支持 Python 2 的最后一个 p4a 版本是v2019.10.06之后的项目主干已全面转向 Python 3。CrystaX NDKp4a 不再支持使用 CrystaX NDK 构建 Python 3最后支持 CrystaX 的版本是0.7.0。如今构建请使用官方 Android NDK可参考仓库中 androidndk.py 对 NDK 版本的探测与约束逻辑。二、Bootstrap 机制理解 p4a 的“后端”概念p4a 支持多种应用后端backend它们提供不同类型的主界面如原生游戏窗口、WebView、纯服务等这些后端统称为Bootstrap。从源码结构看每个 Bootstrap 都是一个独立的目录目录内的__init__.py定义了一个继承自pythonforandroid.toolchain.Bootstrap的类并在模块末尾实例化为bootstrap XxxBootstrap()例如sdl2 后端SDL2GradleBootstrap(SDLGradleBootstrap)name sdl2额外依赖sdl2recipewebview 后端WebViewBootstrap(Bootstrap)name webview额外依赖genericndkbuildservice_library 后端继承ServiceOnlyBootstrap用于产出库文件qt 后端QtBootstrap(Bootstrap)recipe_depends [python3, genericndkbuild, PySide6, shiboken6]且can_be_chosen_automatically False不能自动选择必须显式指定。下面逐一讲解各 Bootstrap 的用法与专属构建选项。三、sdl2 Bootstrap游戏与原生窗口应用3.1 使用方式与适用场景SDL2 是一个广泛使用的跨平台开发库尤其擅长游戏开发。它自带 Android 工程支持p4a 以此为 Bootstrap并向其中注入 Python 构建产物和用于启动 Python 的 JNI 代码。使用方式二选一显式指定--bootstrapsdl2通过 recipe 隐式启用--requirementssdl2,python3从 Python 程序的角度看SDL2 的行为与桌面端一致可以用 Kivy 或 PySDL2 构建应用并直接运行于此 Bootstrappygame_sdl2 理论上可行但当前仓库中尚未提供对应的构建 recipe。3.2 完整构建选项清单sdl2 Bootstrap 支持以下命令行选项列表可能未完全穷尽选项说明--private存放项目文件的目录--package项目 Java 包名如org.example.yourapp--name应用名称--version展示给用户的版本号在 Android 中渲染为versionName--numeric-versionAndroid 的versionCode用于更新排序必须是不大于 2100000000 的正整数--orientation应用支持的显示方向可选portrait、landscape、portrait-reverse、landscape-reverse--manifest-orientation写入AndroidManifest.xml中android:screenOrientation属性的方向值--icon应用图标 png 文件路径--permission声明到AndroidManifest.xml的权限可重复添加--home-app将应用设置为设备主屏桌面启动器应用--display-cutout刘海屏适配策略可选default、shortEdges、never默认never--meta-data追加到应用元数据中的自定义keyvalue对--presplash应用加载期间展示的启动图presplash文件路径--presplash-colorpresplash 背景色格式为#RRGGBB或颜色名red、green、blue等--presplash-lottie用 lottiejson文件作为启动动画指定后将替代静态 presplash 图--wakelock包含该参数时应用将阻止设备休眠--window包含该参数时应用窗口不覆盖 Android 状态栏--blacklist黑名单模式文件路径被匹配的内容从最终 APK 中排除默认./blacklist.txt--whitelist白名单模式文件路径被匹配的内容即使命中黑名单也会保留--add-jar需要打进 APK 的 .jar 文件路径可重复传入以添加多个--intent-filters包含 intent filter 的 XML 文件路径其内容会并入AndroidManifest.xml--service服务名与其应运行的 Python 脚本详见 服务与后台脚本--add-source向应用的 Java 代码中追加一个源码目录--no-byte-compile-python跳过 .py 文件的字节码编译--enable-androidx启用 AndroidX 支持库--add-resource将文件或目录放入 apk 的 res 目录3.3 关键参数的底层实现与取值约束--numeric-version的自动推导与校验。省略该参数时p4a 会从--version自动计算versionCode。其生成逻辑位于 build.py 的get_android_numeric_version把--version按.拆分为数字段并逐段累乘 100 求和最终拼成10 min_sdk version_code的格式旧版本曾用单数字编码 arch多架构时代统一为 10。若--version不是纯数字点分文本p4a 会报错并提示改用--numeric-version显式指定validate_android_numeric_versionbuild.py则强制校验该值必须是大于 0、不大于MAX_ANDROID_VERSION_CODE 2100000000的正整数这是 Google Play 官方文档记载的上限。最终值会写入 AndroidManifest 模板的android:versionCode属性见 AndroidManifest.tmpl.xml。--orientation与多窗口模式的特殊处理。Android 12 默认开启多窗口multi-window模式该模式下系统会忽略android:screenOrientation。因此 p4a 在为 SDL Bootstrap 设置窗口方向提示window orientation hints的同时仅当传入单个方向时才把android:screenOrientation写入具体值如果传入了多个方向则该属性会被置为unspecified。--manifest-orientation则专门用于直接指定 Manifest 中的android:screenOrientation取值合法值全集见 Android 官方android:screenOrientation文档未设置时由--orientation自动合成。--permission的两种语法。--permission接受如下两种写法--permission (nameandroid.permission.WRITE_EXTERNAL_STORAGE;maxSdkVersion18) --permission android.permission.WRITE_EXTERNAL_STORAGE第一种语法用于为权限附加额外属性目前仅支持android:maxSdkVersion和android:usesPermissionFlags第二种用于不需要任何附加属性的场景。警告仅写权限名而不带前缀的旧语法--permission VIBRATE目前仍向后兼容可用但未来将被移除新项目请务必使用带完整android.permission.前缀的写法。图标与启动画面的处理位置。在 build.py 中可以看到--icon未指定时使用默认模板templates/kivy-icon.png文件会被复制为mipmap/icon.png若同时提供--icon-fg前景与--icon-bg背景则可生成 Android 自适应图标adaptive icon且二者必须成对提供否则会打印警告并忽略。--presplash-lottie存在时JSON 文件被写入res/raw/splashscreen.json作为加载动画资源。四、webview BootstrapWebView Python Web 服务4.1 使用方式与工作原理webview Bootstrap 的 GUI 正如其名一个加载本地网页的 WebView但网页由设备上的 Python Web 服务器托管。例如你的 Python 代码可以启动一个 Flask 应用APK 中的 WebView 随即展示该网站并允许用户浏览。使用方式二选一--bootstrapwebview包含webviewjnirecipe--requirementswebviewjni,python3注意Flask 脚本必须以不带debugTrue的方式启动 Web 服务器。调试模式在 Android 上依赖子进程机制无法正常工作。WebView 默认访问 localhost 的5000 端口Flask 默认端口可通过--port修改。如果服务器尚未就绪例如首次启动时 Python 解释器仍在加载的短暂窗口期WebView 会先显示加载页直到服务器可用。4.2 完整构建选项清单--private项目文件目录--packageJava 包名如org.example.yourapp--name应用名称--version展示版本号versionName--numeric-versionversionCode正整数且不大于2100000000省略时由--version计算计算值超限时应把展示版本留在--version中同时用--numeric-version设置合法值--orientation展示方向portrait、landscape、portrait-reverse、landscape-reverse。由于 Android 12 多窗口模式默认忽略android:screenOrientation该设置不保证生效建议在应用内实现自定义方向变更处理器--manifest-orientation写入android:screenOrientation的属性值未设置时由--orientation合成--icon图标 png 路径--permission应用权限名如--permission VIBRATE可重复传入--meta-data自定义keyvalue元数据--presplash加载期启动图路径--presplash-colorpresplash 背景色#RRGGBB或颜色名--wakelock阻止设备休眠--window不覆盖状态栏--blacklist黑名单模式文件默认./blacklist.txt--whitelist白名单模式文件--add-jar附加 .jar可重复传入--intent-filters并入 Manifest 的 intent filter XML--service服务名 运行的 Python 脚本详见 服务与后台脚本--add-source追加 Java 源码目录--portWebView 访问的 localhost 端口默认 5000五、service_library Bootstrap产出可复用的 Python 服务库使用--bootstrapservice_library可将项目构建为AARAndroid Archive输出目标生成包含 Python 服务的库文件供其他构建系统与框架集成复用。该 Bootstrap 的构建选项如下--private项目文件目录--packageJava 包名--name库名称--version版本号--service服务名 运行的 Python 脚本详见 服务与后台脚本--blacklist从最终 AAR 排除的模式文件默认./blacklist.txt--whitelist即使命中黑名单也保留的模式文件--add-jar附加 .jar可重复传入--add-source追加 Java 源码目录六、Qt BootstrapPySide6 桌面框架上 Android6.1 使用方式与限制Qt Bootstrap 可用--bootstrapqt启用或通过包含PySide6、shiboken6recipe 间接启用例如--requirementspyside6,shiboken6。目前使用该 Bootstrap 的唯一途径是PySide6 官方配套的pyside6-android-deploy工具仓库中的PySide6与shiboken6recipe 是动态创建的该工具会先为特定 Android 平台构建出对应 wheelrecipe 仅负责解包这些 wheeltestapps/test_qt/recipes/下有对应的测试 recipe 示例。注意pyside6-android-deploy工具及 Qt Bootstrap当前不支持多架构multi-architecture构建。这一点在 qt 后端源码 中也有印证assemble_distribution会检查len(self.ctx.archs) 1并直接抛出ValueError。6.2 背景概念速览Qt广泛使用的跨平台 C GUI 应用开发框架PySide6Qt6 的官方 Python 绑定让 Python 开发者可以访问完整的 Qt6 APIShiboken6从 C 代码生成 Python 绑定的绑定生成器。注意仓库中的shiboken6recipe 对应的是 Shiboken Python 模块提供若干用于检视与调试 PySide6 代码的实用函数并非生成器本体。6.3 Qt Bootstrap 专属构建选项pyside6-android-deploy的工作方式是生成一个buildozer.spec文件再借助 buildozer 把构建选项传递给使用 Qt Bootstrap 的 p4a。除各 Bootstrap 通用的构建选项外Qt Bootstrap 引入了以下 3 个新选项--qt-libs要加载的 Qt 库模块列表--load-local-libs要加载的 Qt 插件库列表--init-classes需要从--add-jar提供的 Qt jar 文件中加载的 Java 类名列表。这三个选项由pyside6-android-deploy自动填充但你可以通过修改生成的buildozer.spec进行调整。此外该工具还会根据应用实际使用的 PySide6 模块自动推导应传入--permission、--add-jar的值。七、需求黑名单面向 APK 体积的优化手段p4a 默认会像桌面发行版一样为 Python 打包“电池全满”的标准库及其依赖包括 openssl、sqlite3 以及其他你可能根本用不到的组件这会使 APK 体积明显膨胀。针对这一点p4a 提供了--blacklist-requirements选项可剔除核心组件以减小体积p4a apk ... --blacklist-requirementssqlite3目前支持黑名单化的核心组件如下黑名单项影响android禁用 p4a 的 android 模块见 android 模块 API 参考libffi禁用 ctypes 标准库模块openssl禁用 ssl 标准库模块sqlite3禁用 sqlite3 标准库模块该选项的底层解析位于 toolchain.pybuild_dist_from_args会把--blacklist-requirements的值按逗号切分空串会被视为空列表随后在get_recipe_order_and_bootstrap计算 recipe 构建顺序时过滤掉被黑名单命中的内部 recipe从而跳过对应组件的编译与打包。选项本身的注册可见 toolchain.py其 help 文案明确说明这是“用于禁用 Python 3 核心模块以节省空间”的内部 recipe 黑名单机制。需要强调的是黑名单直接决定哪些核心 recipe 不参与构建因此只有在你确认应用确实不需要对应能力时才应使用——例如应用不依赖 SSL 且不访问网络才可安全黑名单化openssl。八、综合实战示例将上述选项组合起来一个典型的 sdl2 应用构建命令如下p4a apk \ --bootstrapsdl2 \ --requirementspython33.10.11,hostpython33.10.11,kivy \ --private /path/to/your/project \ --package org.example.yourapp \ --name MyApp \ --version 1.2.3 \ --orientation portrait \ --icon /path/to/icon.png \ --presplash /path/to/presplash.jpg \ --presplash-color #FFFFFF \ --permission android.permission.INTERNET \ --permission (nameandroid.permission.WRITE_EXTERNAL_STORAGE;maxSdkVersion18) \ --blacklist-requirementssqlite3,libffi \ --wakelock该命令演示了本文涉及的大部分能力锁定 Python 版本、指定后端、设置包名与展示名、自动推导versionCode1.2.3可正常参与数值计算、限定竖屏、自定义图标与启动画面、按两种语法声明权限以及通过黑名单压缩 APK 体积。九、总结p4a 的构建选项体系围绕“Bootstrap 选择 通用/专属参数 体积控制”三层展开sdl2面向游戏与原生窗口应用webview面向 WebView 本地 Python Web 服务service_library面向库产出qt则通过 PySide6 生态工具驱动--numeric-version等参数背后有build.py的严格校验逻辑支撑--blacklist-requirements则从 recipe 层面精准剔除核心组件。理解这些参数与底层实现的对应关系你就能在一条命令行内完成对 APK 外观、权限、版本与体积的全面控制。赞分享开发工具构建工具移动开发【免费下载链接】python-for-androidTurn your Python application into an Android APK项目地址https://gitcode.com/gh_mirrors/py/python-for-android点击查看免费下载相关推荐python-for-android 命令行完全指南toolchain.py 全部命令与参数详解python for android 命令行完全指南toolchain.py 全部命令与参数详解 本篇指南以 python for androidp4a官开发工具构建工具移动开发Maple Mono构建参数详解命令行选项全解析Maple Mono构建参数详解命令行选项全解析 Maple Mono作为一款优秀的开源等宽字体提供了丰富的构建选项来满足不同用户的需求。本文将深入解析Ma开发工具broot 动词Verbs完全指南选择参数、用户参数与外部命令执行机制broot 动词Verbs完全指南选择参数、用户参数与外部命令执行机制 broot 中几乎所有交互动作都由动词Verb驱动无论是切换显示模式、删开发工具上一篇如何使用golang-migrate/migrate管理数据库资源组下一篇10分钟掌握mojs渐变动画从入门到高级技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考