PyInstaller无法正确构建cairo.Context问题求助

安全阿岳

2026-8-16

问题

调试过程中已更新描述和标题补充信息。我有一个需打包为可执行文件的Python应用，依赖python-gi-cairo等库实现绘图功能。启动打包后的程序时，终端报错：

TypeError: Couldn't find foreign struct converter for 'cairo.Context'

我已制作了一个最小化的绘图测试应用来验证PyInstaller参数。对应的evms.spec文件内容如下：

# -*- mode: python ; coding: utf-8 -*-


block_cipher = None


a = Analysis(
    ['evms.py'],
    pathex=[],
    binaries=[],
    datas=[],
    hiddenimports=['matplotlib', 'python-gi-cairo'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='evms',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=True,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
)

解决方案

针对这个PyInstaller打包时丢失cairo转换器的问题，可以尝试以下几种解决方式：

补充隐藏依赖导入
修改spec文件中的hiddenimports，添加gi.repository.cairo和cairo，确保PyInstaller能识别到深层依赖：
```
hiddenimports=['matplotlib', 'python-gi-cairo', 'gi.repository.cairo', 'cairo'],
```

添加自定义钩子文件
在spec文件所在目录创建hook-gi.repository.cairo.py，内容如下：

from PyInstaller.utils.hooks import collect_glib_share_files, collect_glib_translations

datas = collect_glib_share_files('cairo')
datas += collect_glib_translations('cairo')

然后在spec的hookspath中指定钩子目录，比如：

hookspath=['.'],

禁用UPX压缩
UPX压缩可能会损坏cairo相关的二进制文件，将spec中upx=True改为upx=False，重新打包测试。
确认系统依赖完整
打包环境需安装完整的cairo系统库，以Debian/Ubuntu为例：
```
sudo apt-get install libcairo2-dev
```

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