跨平台移动开发桌面应用UI组件【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址https://gitcode.com/gh_mirrors/ki/kivy点击查看免费下载本文是一份面向 Kivy 开发者的环境变量技术手册系统梳理 Kivy 通过环境变量控制运行时行为的所有入口从数据/模块/配置目录的路径定位到核心 Provider 的选择与回退再到 DPI 指标模拟、OpenGL 图形后端与异步事件循环切换。读完本文你将掌握在启动应用前用一行环境变量完成文本渲染后端替换、Provider 优先级定制、多应用配置隔离、移动端屏幕指标模拟等实战能力并理解这些变量在 kivy/init.py 与 kivy/core/init.py 中的底层生效机制。环境变量的两条铁律Kivy 提供大量环境变量来控制框架的初始化和行为。使用它们之前必须记住两条规则必须在导入 kivy 之前设置。绝大多数环境变量只在import kivy的瞬间被读取一次之后修改不会生效。命令行与 Python 内设置等价。既可以在 shell 中设置也可以在脚本开头用os.environ写入$ KIVY_TEXTpil python main.py等价于 Python 代码import os os.environ[KIVY_TEXT] pil import kivy从源码看这一机制的核心位于 kivy/init.py模块导入时遍历kivy_options中的每一项若在environ中找到KIVY_CATEGORY键就会用environ[key].split(,)把逗号分隔的 Provider 列表写入kivy_options供后续核心模块读取。因此任何 Provider 相关的变量都支持逗号分隔的优先级列表。路径控制Path control版本引入1.0.7Kivy 允许通过环境变量重定向配置、模块和数据的默认存放目录这在定制安装、便携化部署和多实例运行时非常有用。KIVY_DATA_DIRKivy 数据目录的位置默认是kivy 安装路径/data。它决定了字体、图片、glsl 着色器等内置资源的查找根目录。对应源码实现见 kivy/init.pykivy_data_dir environ.get(KIVY_DATA_DIR, join(kivy_base_dir, data))KIVY_MODULES_DIRKivy 模块目录默认是kivy 安装路径/modules即仓库中的 kivy/modules 目录。它控制kivy.modules下内置模块console、inspector、monitor、showborder 等的查找位置。源码见 kivy/init.pykivy_modules_dir environ.get(KIVY_MODULES_DIR, join(kivy_base_dir, modules))KIVY_HOMEKivy 用户主目录用于存放本地配置文件config.ini、日志、mods用户模块和图标缓存必须位于可写位置。不同平台默认值不同桌面平台用户主目录/.kivyAndroidandroid app 路径/.kivyiOS用户主目录/Documents/.kivyAndroid/iOS 默认值自 1.9.0 起支持。配置文件名固定为KIVY_HOME/config.ini用户模块目录为KIVY_HOME/mods见 kivy/init.py。KIVY_DESKTOP_PATH_ID桌面应用专属目录标识版本引入3.0.0这是面向桌面平台的应用专属目录机制。设置后Kivy 会为当前应用生成独立于全局.kivy的配置与日志目录便于最终用户在文件系统中识别哪个目录属于哪个应用也支持多个 Kivy 应用之间配置与日志完全隔离。关键行为均可在 kivy/init.py 中找到对应实现标识符会经过normalize_path_id做文件系统安全归一化/ \ : * ? |等非法字符被替换为下划线。归一化后的标识符用于构造KIVY_HOME、user_data_dir和user_cache_dir。在桌面平台上优先级高于KIVY_HOME环境变量和虚拟环境检测。在 iOS/Android 等移动平台被忽略这些平台的文件系统用户不可浏览。若桌面平台未设置此变量路径构造会回退到使用App.name从 App 类名派生并打印一条建议设置该变量的警告日志。设置示例取值为My Photo EditorWindows%APPDATA%\My_Photo_Editor\.kivymacOS~/Library/Application Support/My_Photo_Editor/.kivyLinux~/.local/share/My_Photo_Editor/.kivyPython 中的标准用法必须在导入 kivy 前import os os.environ[KIVY_DESKTOP_PATH_ID] My Photo Editor import kivy给移动端开发者的提示如果你在桌面平台开发移动应用可以把这个变量设为任意值来抑制警告——该变量对移动应用本身没有任何效果只是开发期不再报警告对应逻辑见 kivy/app.py 与 kivy/init.py。KIVY_SDL3_PATH 与 KIVY_SDL3_FRAMEWORKS_SEARCH_PATH编译期 SDL3 定位版本引入3.0.0KIVY_SDL3_PATH若设置编译 Kivy 时使用该路径下的 SDL3 库和头文件而非系统级安装版本。运行Kivy 应用时若要用同一套库还必须把该路径加到PATH环境变量最前面。KIVY_SDL3_FRAMEWORKS_SEARCH_PATH仅 macOS 使用。必须包含SDL3.framework、SDL_image.framework、SDL_mixer.framework、SDL_ttf.framework四个框架。两个变量都带警告它们是编译 Kivy 所必需但运行程序并不需要。KIVY_DEPS_ROOT构建期依赖根目录版本引入2.2.0若设置构建期间 Kivy 会以此目录为根搜索依赖目前仅 SDL。注意优先级若同时设置了KIVY_SDL3_PATH或KIVY_SDL3_FRAMEWORKS_SEARCH_PATH则优先使用后两者。同样仅编译需要运行不需要。配置Configuration跳过用户配置KIVY_USE_DEFAULTCONFIG只要出现在环境中Kivy 就不读取用户配置文件即不加载KIVY_HOME/config.ini。Kivy 自身的测试套件大量使用它来保证测试环境纯净例如 kivy/tests/fixtures.py 与 kivy/tests/common.py 中均有environ[KIVY_USE_DEFAULTCONFIG] 1。KIVY_NO_CONFIG设置后既不读也不写任何配置文件同样适用于用户配置目录意味着KIVY_HOME下也不会自动创建config.ini见 kivy/init.py 中makedirs与写配置的守卫条件。控制日志输出KIVY_NO_FILELOG设置后日志不写入文件。KIVY_NO_CONSOLELOG设置后日志不打印到控制台。这两个变量的底层实现在 kivy/logger.py文件日志处理器的安装条件是KIVY_NO_FILELOG not in os.environ控制台处理器的安装条件是sys.stderr and KIVY_NO_CONSOLELOG not in os.environ。此外 kivy/logger.py 还提供了KIVY_LOG_MODE取值为KIVY、PYTHON、MIXED来控制日志输出模式可与此二变量配合使用。KIVY_NO_ARGS接管命令行参数版本引入1.9.0设置为true、1或yes之一时Kivy不再解析命令行参数。这样你就可以在脚本里自由使用自己的参数而无需借助--分隔符import os os.environ[KIVY_NO_ARGS] 1 import kivy从 kivy/init.py 可以看出Kivy 默认会解析-h/--help、-d/--debug、-c/--config、-p/--provider、--size、--dpi等自身选项设置KIVY_NO_ARGS后整个 getopt 解析流程被跳过sys.argv原样保留给应用。KCFG_section_key用环境变量注入配置项版本引入1.11.0只要检测到KCFG_section_key格式的环境变量就会被映射到全局Config对象上。它们只在import kivy时加载一次并且优先级高于已加载的config.ini见 kivy/config.py 的说明。import os os.environ[KCFG_KIVY_LOG_LEVEL] warning import kivy # 导入期间等价于执行 # Config.set(kivy, log_level, warning)命令行示例KCFG_GRAPHICS_FULLSCREENauto python main.py KCFG_KIVY_LOG_LEVELwarning python main.py底层实现位于 kivy/config.pyConfig初始化后遍历environ凡是KCFG_开头的键按_拆分为section和name均为小写校验 section 存在后调用Config.set(section, name, value)未知格式或未知 section 会打印警告。注意 section 名中不允许出现下划线这是 kivy/config.py 中明确说明的限制因为下划线正是分隔符。KIVY_NO_ENV_CONFIG禁用环境配置映射版本引入1.11.0设置后任何环境变量都不会被映射到 Config 对象不设置时所有KCFG_section_keyvalue都会被映射os.environ[KIVY_NO_ENV_CONFIG] 1限制核心模块使用特定实现Provider 选择kivy.core会为每个核心模块窗口、文本、视频、音频、图片、相机等自动挑选当前平台下最佳的实现。但在测试、自定义安装或需要强制某实现时你可以用KIVY_CATEGORY系列变量手动限制选择器。逗号分隔的优先级列表每个变量都可以传逗号分隔的 Provider 列表作为优先级顺序。Kivy 按列表顺序逐个尝试使用第一个成功初始化的 Provider。例如$ KIVY_IMAGEsdl3,pil python main.py或import os os.environ[KIVY_IMAGE] sdl3,pil import kivy上面这行会先尝试 sdl3 图像 Provider如果 sdl3 不可用、或目标文件格式不被 sdl3 支持则回退到 pil。解析逻辑在 kivy/init.pykivy_options[option] environ[key].split(,)随后core_select_lib/core_register_libs按此顺序尝试导入 Provider 模块见 kivy/core/init.py。而各 Provider 的注册表名称→模块映射集中定义在 kivy/core/init.py 的PROVIDER_CONFIGS中。完整 Provider 变量一览变量作用可选值KIVY_WINDOW创建 Window 的实现sdl3、x11、egl_rpiKIVY_TEXT文本渲染实现sdl3、pil、sdlttfKIVY_VIDEO视频渲染实现gstplayer、ffpyplayer、ffmpeg、android、nullKIVY_AUDIO_OUTPUT音频播放实现sdl3、gstplayer、ffpyplayer、avplayerKIVY_IMAGE图像读取实现sdl3、pil、imageio、tex、dds2.0.0 起移除了 GPL 的gif实现KIVY_CAMERA相机读取实现avfoundation、android、opencvKIVY_SPELLING拼写检查实现enchant、osxappkitKIVY_CLIPBOARD剪贴板管理实现sdl3、dummy、wayland、android需要说明的是以上取值表是原文档的权威清单而当前仓库的PROVIDER_CONFIGS见 kivy/core/init.py还登记了更多 Provider如 pango 文本、thorvg_svg 图像、winctypes/xsel/xclip 剪贴板、picamera 相机等实际可用集合以你安装的 Kivy 版本和编译配置为准用KIVY_CATEGORY指定不在你环境中的 Provider 时选择器会跳过它并尝试下一个。按实例选择 Provider部分核心模块支持按实例选择 Provider即同一个应用内不同对象可以使用不同的实现。相关模块kivy.core.audio_output—— 音频 Provider 的按实例选择kivy.core.image—— 图像 Provider 的按实例选择kivy.core.text—— 文本 Provider 的按实例选择这一机制的通用加载逻辑含 Provider 校验、格式兼容性检查和回退实现在 kivy/core/init.py 的load_with_provider_selection中图像/文本/音频模块分别调用它例如 kivy/core/image/init.py 与 kivy/core/text/init.py。KIVY_PROVIDER_STRICT严格模式若想让 Provider 失败直接抛异常而不是静默回退可以设置KIVY_PROVIDER_STRICT取1、true或yes。严格模式下请求的 Provider 不存在 → 抛ValueErrorProvider 不支持该文件格式 → 抛ValueErrorProvider 加载失败 → 抛Exception非严格模式则打印Logger.warning并回退到默认优先级。判定函数_is_strict_mode见 kivy/core/init.py使用示例见 kivy/core/text/init.pyos.environ[KIVY_PROVIDER_STRICT] 1指标MetricsMetrics 相关的环境变量用于手动控制 DPI、密度和字体缩放是模拟移动设备屏幕的利器。需要特别注意的是指标值在运行时不可修改——一旦某个值被换算成像素就再也无法还原因为设备的 DPI 和密度在运行时本就无法改变见 kivy/metrics.py 的说明。变量作用引入版本KIVY_DPI用作Metrics.dpi的值1.4.0KIVY_METRICS_DENSITY用作Metrics.density的值1.5.0KIVY_METRICS_FONTSCALE用作Metrics.fontscale的值1.5.0读取逻辑位于 kivy/metrics.py导入模块时从environ取这三个变量并转为 float。文档中的参考取值Android 上 density 通常在0.75、1、1.5、2之间变化fontscale 通常在0.81.2之间。模拟高密度屏类似 HTC One XKIVY_DPI320 KIVY_METRICS_DENSITY2 python main.py --size 1280x720模拟中密度屏类似 Motorola Droid 2KIVY_DPI240 KIVY_METRICS_DENSITY1.5 python main.py --size 854x480模拟用户对字体缩放的偏好KIVY_METRICS_FONTSCALE1.2 python main.py注意KIVY_DPI只影响dpi不会影响dp/sp单位因为dp/sp基于的是屏幕密度而非 DPI。另外kivy/modules/screen.py 中的 screen 模块模拟不同屏幕尺寸的调试模块在运行时也会动态设置KIVY_METRICS_DENSITY与KIVY_DPI用于在桌面模拟其他设备的像素密度。图形Graphics变量作用KIVY_GL_BACKEND选择 OpenGL 后端详见kivy.graphics.cglKIVY_GL_DEBUG是否记录 OpenGL 调用日志KIVY_GRAPHICS是否强制使用 OpenGL ES2这三者的实现集中在 kivy/graphics/cgl.pyxKIVY_GL_BACKEND在模块导入时被读取用于选择后端KIVY_GL_DEBUG 1时开启所有 GL 调用的日志KIVY_GRAPHICS gles会强制 OpenGL ES2实际上 ES2 在启用时总是被使用。KIVY_GLES_LIMITSGLES2 限制开关版本引入1.8.1是否强制 GLES2 限制默认强制即默认值为 1设为 false 时 Kivy 将不再真正 GLES2 兼容。开启后的潜在不兼容点如下项目说明Mesh indices单个 mesh 的索引数被限制为 65535Texture blit向纹理 blit 时数据颜色与缓冲格式必须与创建纹理时使用的格式一致。桌面上驱动能正确处理不同颜色的转换而 Android 上多数设备会失败相关源码GLES 限制默认值取自KIVY_GLES_LIMITS见 kivy/graphics/vertex_instructions.pyx桌面默认 0移动平台默认 1与 kivy/graphics/texture.pyx当 mesh 索引或纹理 blit 超出限制时两者都会打印 consider setting KIVY_GLES_LIMITS 之类的提示日志见 kivy/graphics/texture.pyx、kivy/graphics/vertex_instructions.pyx。Raspberry Pi 显示控制egl_rpi 窗口 ProviderKIVY_BCM_DISPMANX_ID修改使用egl_rpi窗口 Provider 时默认的 Raspberry Pi 显示器。可选值定义在vc_dispmanx_types.h中默认值 00DISPMANX_ID_MAIN_LCD1DISPMANX_ID_AUX_LCD2DISPMANX_ID_HDMI3DISPMANX_ID_SDTV4DISPMANX_ID_FORCE_LCD5DISPMANX_ID_FORCE_TV6DISPMANX_ID_FORCE_OTHERKIVY_BCM_DISPMANX_LAYER修改 egl_rpi 窗口 Provider 的 dispmanx 层默认值 01.10.1 引入。两者在 kivy/core/window/window_egl_rpi.py 中以int(environ.get(...))方式读取。事件循环Event Loop版本引入2.0.0KIVY_EVENTLOOP决定应用以异步方式运行时使用哪个异步库详见kivy.app的使用示例asyncio应用异步运行时使用标准库asyncio。未设置时的默认值。trio应用异步运行时使用trio包。在 kivy/app.py 的说明中异步运行需要把async_runTouchApp或App.async_run协程调度到目标库的事件循环中KIVY_EVENTLOOP环境变量或async_runTouchApp/async_run的async_lib参数均可指定异步库后者优先级更高二者取值必须一致否则协程无法被正确调度。asyncio 示例import asyncio from kivy.app import async_runTouchApp from kivy.uix.label import Label async def main(): await async_runTouchApp(Label(textHello, World!), async_libasyncio) asyncio.run(main())trio 示例import trio from functools import partial from kivy.app import async_runTouchApp from kivy.uix.label import Label async def main(): async_runTouchApp_func partial(async_runTouchApp, async_libtrio) await trio.run(async_runTouchApp_func, Label(textHello, World!)) trio.run(main)对应实现入口为 kivy/app.py 的App.async_run(async_libNone)它内部把async_lib透传给async_runTouchApp。实战小结把本文涉及的变量按使用场景归类多应用配置隔离KIVY_DESKTOP_PATH_ID桌面3.0.0 起、KIVY_HOME通用路径覆盖。纯净/可移植环境KIVY_USE_DEFAULTCONFIG跳过用户配置、KIVY_NO_CONFIG不读不写配置、KIVY_NO_ARGS独占命令行参数。日志管控KIVY_NO_FILELOG、KIVY_NO_CONSOLELOG、KIVY_LOG_MODE或直接用KCFG_KIVY_LOG_LEVELwarning调低日志级别。Provider 调优与排障KIVY_CATEGORY指定实现与优先级、KIVY_PROVIDER_STRICT1让失败快速暴露、各核心模块文档如 kivy/core/image/init.py、kivy/core/text/init.py、kivy/core/audio_output/init.py还提供了按实例选择的进阶用法。屏幕/渲染调试KIVY_DPI、KIVY_METRICS_DENSITY、KIVY_METRICS_FONTSCALE模拟不同设备KIVY_GL_BACKEND、KIVY_GL_DEBUG、KIVY_GLES_LIMITS控制图形后端与兼容性。异步化KIVY_EVENTLOOPasyncio|trio配合async_run/async_runTouchApp使用。最后再次强调以上所有环境变量都必须在import kivy之前设置完成否则不会生效。赞分享跨平台移动开发桌面应用UI组件【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址https://gitcode.com/gh_mirrors/ki/kivy点击查看免费下载相关推荐CAICybersecurity AI配置完全指南环境变量、OpenRouter 集成与 Provider 路由控制CAICybersecurity AI配置完全指南环境变量、OpenRouter 集成与 Provider 路由控制 本文以 CAICybersecur人工智能AI Agent网络安全渗透测试工具调用AI 评测SWE-agent 环境变量完全指南密钥注入、配置路径解析与日志控制SWE agent 环境变量完全指南密钥注入、配置路径解析与日志控制 本文系统梳理 SWE agentNeurIPS 2024 开源的自动修复 GitHubAI AgentAgent 框架代码智能体后端开发工具CANN SHMEM 环境变量完全指南UID 初始化、多实例端口、RDMA 与 Profiling 配置详解CANN SHMEM 环境变量完全指南UID 初始化、多实例端口、RDMA 与 Profiling 配置详解 导读 CANN SHMEM 作为昇腾平台面向多机通信高性能计算人工智能CANNAscend上一篇腾讯柠檬清理网络测速功能原理LemonNetSpeed模块技术剖析 下一篇Spinnaker自定义健康检查确保部署成功的关键创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考