使用RstDocument部署Kivy应用失败求助：PC正常替换Label可部署

看起来你遇到的问题很典型——PC端跑起来完全正常，一打包部署就挂，换成Label组件又能正常工作，这大概率是RstDocument的依赖没被正确打包，或者打包工具没识别到这个组件的隐含依赖。下面一步步来排查和解决：

1. 先确认RstDocument的核心依赖是否完整 #

RstDocument依赖docutils库（用来解析reStructuredText语法），PC端你可能已经手动装了，但打包时如果没把这个库包含进去，部署后必然会报错。

• 先在开发环境里确认docutils已安装：

  pip install docutils
  

• 如果用Buildozer打包Android，一定要在buildozer.spec的requirements里加上它：

  requirements = python3,kivy,docutils
  

• 如果用PyInstaller打包桌面程序，要确保docutils被纳入打包范围，比如在.spec文件里的hiddenimports补充：

  hiddenimports = ['docutils', 'kivy.uix.rstdocument']
  

2. 避免打包工具误删未显式引用的组件 #

很多打包工具（比如PyInstaller）会自动剔除它认为“未被使用”的代码，如果你是通过kv文件使用RstDocument的，Python代码里没有显式导入，就容易被漏掉。

• 最简单的解决方法：在你的Python代码开头显式导入RstDocument，哪怕你没直接在代码里实例化它：

  from kivy.uix.rstdocument import RstDocument
  

  这样打包工具就会识别到这个组件被使用了，不会把它从打包包中剔除。

3. 一定要看部署时的错误日志 #

光说“部署失败”太模糊，得抓具体报错信息才能精准定位：

• 如果是Buildozer打包Android，用adb查看日志：

  adb logcat | grep python
  

• 如果是PyInstaller打包的桌面程序，别直接双击exe，打开命令行窗口运行它，就能看到具体的错误提示（比如找不到docutils模块，或者找不到RstDocument类）。

4. 用最小测试案例验证 #

写一个极简的测试程序，只包含RstDocument，看看能不能打包成功：

import kivy
from kivy.app import App
from kivy.uix.rstdocument import RstDocument

class TestRstApp(App):
    def build(self):
        return RstDocument(text='**Hello RST Test**\n\nThis is a test paragraph.')

if __name__ == '__main__':
    TestRstApp().run()

如果这个小例子能打包成功，说明你的主程序里有其他冲突或配置问题；如果也失败，那就是打包环境的版本兼容性问题——比如Kivy版本和docutils版本不匹配。

5. 版本兼容性排查 #

某些旧版Kivy可能和新版docutils有冲突，你可以尝试指定稳定版本组合安装：

pip install kivy==2.1.0 docutils==0.19

这个组合经过不少开发者验证，兼容性比较好，你可以根据自己的需求调整版本号。

内容的提问来源于stack exchange，提问作者Psionman