Win10下如何用SIP封装Qt5(C++)给Python调用？封装失败求解决

API 探路者

2026-5-21

使用SIP封装Qt5 C++代码为Python包装器的解决方案

我最近尝试用SIP把自己写的Qt5（C++）代码封装成Python能用的包装器，但折腾了半天一直失败，想请教下解决办法。我用的软件版本如下：

QT 5.9.1 MSVC2015
PYQT 5.9.1
PYTHON 3.6.4
SIP 4.19.8

我的代码文件：

foo.h

#ifndef FOO_H
#define FOO_H
#if defined(FOO_LIBRARY)
#define FOOSHARED_EXPORT __declspec(dllexport)
#else
#define FOOSHARED_EXPORT __declspec(dllimport)
#endif
FOOSHARED_EXPORT int len(const char* str);
#endif //FOO_H

foo.cpp

#include <string.h>
#include "foo.h"
int len(const char* str) {
    return strlen(str);
}

foo.sip（我可能写得有问题，麻烦帮忙检查）

注：这里我没写全正确的SIP文件内容，希望能得到正确的示例和编译指导

针对这个场景的解决步骤：

1. 编写正确的SIP文件

首先，你的foo.sip得符合SIP的语法规范，针对这个简单的函数，正确的SIP文件应该是这样的：

%Module foo 1.0

int len(const char* str);

%Module是必须项，用来指定模块名和版本号
直接声明要导出的函数即可，SIP会自动处理const char*到Python字符串的类型转换

2. 编译C++动态库（DLL）

用Qt Creator或者MSVC编译foo.cpp生成foo.dll：

确保项目设置里定义了FOO_LIBRARY（这样FOOSHARED_EXPORT会被解析为__declspec(dllexport)，保证函数能被正确导出）
编译目标位数要和Python一致：如果你的Python 3.6.4是64位，就编译64位DLL；32位Python则对应32位编译

3. 用SIP生成包装器代码并编译

打开匹配版本的MSVC命令提示符（比如MSVC2015 x64），按以下步骤操作：

先确认Python和Qt的环境变量已配置，确保能找到sip.exe和qmake.exe
生成Python包装器的C++代码：
```
sip -c ./build foo.sip
```
这会在build目录下生成对应的包装器代码

创建setup.py文件，用来编译成Python扩展模块：

from setuptools import setup, Extension

foo_module = Extension(
    '_foo',
    sources=['build/sipfoo.cpp'],
    libraries=['foo'],  # 链接你生成的foo.dll
    library_dirs=['./path/to/foo/dll'],  # 替换为foo.dll实际所在的目录
)

setup(
    name='foo',
    version='1.0',
    ext_modules=[foo_module],
    py_modules=['foo'],
)

最后执行编译安装：
```
python setup.py install
```

4. 常见问题排查

编译器不匹配：必须使用和编译Python、Qt一致的MSVC版本（你用的MSVC2015是正确的，因为Python 3.6.4正是基于该版本编译）
DLL路径问题：编译后的foo.dll要放在Python能加载到的路径，或者在setup.py中准确指定library_dirs
SIP语法错误：如果SIP生成代码失败，检查foo.sip的语法，比如模块声明是否正确、函数签名是否和C++代码完全一致
导出符号问题：用dumpbin /exports foo.dll命令检查len函数是否被正确导出，如果没导出，确认编译时是否定义了FOO_LIBRARY

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