【Kivy App】Kivy全平台安装指南（重点讲解UOS适配问题）

以下是 Kivy 全平台安装指南，重点针对 统信UOS（Deepin/UOS） 的适配问题和解决方案，同时涵盖其他主流平台（Windows/macOS/Android/iOS）的安装配置。

---

1. Kivy 全平台安装概览

平台	安装方式	核心依赖
Windows	pip install kivy[full]	OpenGL 兼容显卡、Python 3.7+
macOS	pip install kivy[full] + 解决 SDL2 依赖	Homebrew 安装 sdl2/ffmpeg
Linux/UOS	pip install kivy[full] + 解决 GPU/输入法兼容性	libgl1-mesa-dev、ibus 输入法支持
Android	通过 Buildozer 打包（需配置 JDK/Android SDK/NDK）	Java 11、Android SDK 30+
iOS	通过 kivy-ios 工具链（仅限 macOS 环境）	Xcode、Cython

---

2. 统信UOS（Deepin/UOS）专属安装指南

2.1 系统级依赖安装

统信UOS基于 Debian，但需额外解决 GPU 驱动 和 输入法兼容性：

# 1. 安装基础编译工具和图形库
sudo apt update
sudo apt install -y \
    python3-pip python3-dev \
    libgl1-mesa-dev libgles2-mesa-dev \  # OpenGL ES 支持
    libsdl2-dev libmtdev-dev \           # Kivy 输入依赖
    ibus libibus-1.0-dev                 # 输入法支持（解决中文输入崩溃）

# 2. 确保 Wayland/X11 兼容性（UOS默认用Wayland）
export GDK_BACKEND=x11  # 临时切换至X11（推荐）
# 或永久设置：在 ~/.bashrc 中添加此行

2.2 创建 Python 虚拟环境（推荐）

python3 -m venv kivy_env
source kivy_env/bin/activate
pip install --upgrade pip wheel setuptools

2.3 安装 Kivy

# 安装完整版（含音频/视频支持）
pip install kivy[full]

# 验证安装
python -m kivy

• 常见问题：
  • 报错 GLib 缺失：安装 libglib2.0-dev。
  • 无法打开窗口：切换至 X11 会话（注销后选择“X11”登录）。

---

3. 其他平台安装要点

3.1 Windows

# 直接安装（确保已安装最新显卡驱动）
pip install kivy[full]

# 若黑屏/闪退：尝试强制使用 Angle 后端
set KIVY_GL_BACKEND=angle_sdl2
python main.py

3.2 macOS

# 通过 Homebrew 安装依赖
brew install sdl2 ffmpeg

# 安装 Kivy
pip install kivy[full]

3.3 Android（通过 Buildozer）

# 在统信UOS中配置
sudo apt install -y zip unzip openjdk-11-jdk autoconf
pip install buildozer cython

# 初始化项目
buildozer init
buildozer -v android debug  # 首次运行会下载 SDK/NDK（需代理）

3.4 iOS（仅限 macOS）

pip install kivy-ios
toolchain build python3 kivy
toolchain create MyApp ~/myapp

---

4. 统信UOS专属问题解决

问题1：中文输入法崩溃

症状：输入中文时 Kivy 应用闪退。
解决：安装 IBus 并设置环境变量：

sudo apt install ibus ibus-libpinyin
export GTK_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
export QT_IM_MODULE=ibus

问题2：Wayland 兼容性

症状：窗口无法渲染或鼠标事件无响应。
解决：强制使用 X11：

# 临时方案
export GDK_BACKEND=x11

# 永久方案：修改 ~/.profile 或 ~/.bashrc
echo "export GDK_BACKEND=x11" >> ~/.bashrc

问题3：Buildozer 打包失败

症状：下载 SDK/NDK 超时。
解决：手动下载并配置路径（在 buildozer.spec 中修改）：

[buildozer]
android.sdk_path = /path/to/android-sdk
android.ndk_path = /path/to/android-ndk

---

5. 验证安装

测试代码（main.py）

from kivy.app import App
from kivy.uix.button import Button

class TestApp(App):
    def build(self):
        return Button(text="Hello UOS!")

TestApp().run()

运行：

python main.py

• 预期结果：显示带按钮的窗口，触控/点击正常响应。

---

6. 总结

• 统信UOS重点：
  • 解决 GPU 驱动（libgl1-mesa-dev）和输入法（ibus）兼容性。
  • 强制使用 X11 避免 Wayland 问题。
• 跨平台一致性：
  • 推荐使用虚拟环境隔离依赖。
  • Android 打包需全局安装 JDK/SDK，其他依赖均在虚拟环境中。
• 高级需求：
  • 复杂项目可结合 Pyjnius（Android）或 Pyobjus（iOS）调用原生 API。

通过以上步骤，可在统信UOS及其他主流平台上顺利完成 Kivy 开发环境配置。