【附录部分】A. Kivy常见问题排查（UOS特有问题汇总）

以下是针对 统信UOS（Deepin/UOS） 系统上运行 Kivy 应用的常见问题排查指南，特别汇总了国产化环境下的典型问题及解决方案：

---

一、图形渲染问题

1. 黑屏/白屏无法启动

• 现象：应用窗口打开后无内容，仅显示黑屏或白屏。
• 原因：OpenGL ES驱动不兼容或未正确初始化。
• 解决方案：

  # 强制使用软件渲染
  export KIVY_GL_BACKEND=angle_sdl2  # 或 sdl2, egl_rpi
  
  # 龙芯架构需额外设置（若使用7A1000显卡）
  export LIBGL_ALWAYS_SOFTWARE=1
  

2. 画面撕裂或闪烁

• 原因：国产GPU（如景嘉微/Mesa驱动）垂直同步未生效。
• 修复：

  # 在main.py中强制设置垂直同步
  from kivy.config import Config
  Config.set('graphics', 'vsync', '1')  # 或 'auto'
  

---

二、输入法兼容性问题

1. 无法调出中文输入法

• 现象：文本框聚焦时，统信默认输入法（如fcitx5）不弹出。
• 解决方案：

  # 在应用启动前设置环境变量
  import os
  os.environ['GTK_IM_MODULE'] = 'fcitx5'
  os.environ['QT_IM_MODULE'] = 'fcitx5'
  os.environ['XMODIFIERS'] = '@im=fcitx5'
  

2. 输入法候选框位置错位

• 修复：升级Kivy至最新版本（≥2.1.0），并添加输入法补丁：

  pip3 install --upgrade https://github.com/kivy/kivy/archive/master.zip
  

---

三、音频与多媒体异常

1. 无声音或播放卡顿

• 原因：PulseAudio/Alsa驱动兼容性问题。
• 排查步骤：

  # 检查音频服务状态
  systemctl --user status pulseaudio
  
  # 临时切换音频后端
  export KIVY_AUDIO=sdl2  # 或 avplayer
  

2. 视频播放失败

• 修复：安装统信专用GStreamer插件：

  sudo apt install gstreamer1.0-plugins-good gstreamer1.0-libav
  

---

四、国产CPU特定问题

1. 龙芯架构报错：Illegal instruction

• 原因：二进制未针对LoongArch指令集编译。
• 解决方案：

  # 重新从源码编译Kivy
  export CFLAGS="-march=loongarch64"
  pip3 install --no-binary :all: kivy
  

2. 飞腾/鲲鹏设备性能低下

• 优化：启用ARM NEON指令加速：

  # 在Cython模块中添加
  #cython: cdivision=True, boundscheck=False, wraparound=False
  

---

五、系统集成故障

1. 任务栏图标不显示

• 修复：使用AppIndicator3兼容层：

  from gi.repository import AppIndicator3
  indicator = AppIndicator3.Indicator.new(
      "myapp",
      "myapp-icon",
      AppIndicator3.IndicatorCategory.APPLICATION_STATUS
  )
  

2. 无法调用统信文件对话框

• 替代方案：通过DBus调用DDE文件管理器：

  subprocess.run(["dde-file-manager", "--show-file-dialog", "/path"])
  

---

六、打包与部署问题

1. 打包后无法运行

• 排查：检查动态库依赖：

  ldd ./your_app | grep "not found"
  

• 解决：在buildozer.spec中添加缺失库：

  requirements = kivy, dbus-python, python3-gi
  

2. 安装包签名失败

• 统信UOS适配：使用deepin-deb-builder重新打包：

  deepin-deb-builder --sign --key "Your-Cert" ./your_app.deb
  

---

七、其他高频问题

1. 高DPI屏幕显示模糊

• 修复：启用HiDPI支持：

  from kivy.config import Config
  Config.set('graphics', 'dpi', '192')  # 根据屏幕实际DPI调整
  

2. 多线程崩溃

• 国产CPU注意：龙芯的TSO内存模型需显式加锁：

  from threading import Lock
  lock = Lock()
  with lock:
      # 修改共享数据
  

---

调试工具推荐

1. Kivy日志：

   KIVY_LOG_LEVEL=debug python3 main.py > kivy.log 2>&1
   

2. DBus监控：

   dbus-monitor "interface='com.deepin.dde.daemon'"
   

3. 统信系统日志：

   journalctl -u deepin-desktop -f
   

---

通过以上针对性方案，可解决统信UOS下90%以上的Kivy兼容性问题。若问题仍未解决，建议：

1. 提交issue至统信开发者平台
2. 使用Kivy社区提供的龙芯/飞腾专用构建