★ FEATURED ARTICLE 简介Python调用C/C动态链接库DLL的入门实操型PDF资源面向需要在Python中复用C/C库、兼顾运行效率与上层开发灵活性的开发者、学生及项目维护人员。资源仅含1个PDF文件大小约55KB内容精炼便于按示例边读边练目前已有4761人学习。文档以VS 2005中的DLL工程为例从最简整数相加函数切入演示如何用extern C导出API接口、按__cdecl约定编译生成hello.dll再通过ctypes加载并完成调用第二个示例进阶到结构体传参利用ctypes.Structure定义与C端一致的StructTest借助指针、argtypes与restype设置让字符串、整型数组等字段在Python侧可见并正确返回。文末还总结64位Python加载32位DLL、字节对齐、try/except异常处理等常见坑点并提示调用约定与接口声明的关键细节。整体内容虽短却覆盖了Python与C/C跨语言调用的核心链路适合快速入门与排错参考。1. 为什么 Python 要调 C DLL不是图省事是图性能手里攥着一个几十年前的 C 算法库或者是某个硬件厂商只给了 C/C 接口的 SDK这时候用 Python 重写一遍不现实更不划算。Python 调用 C/C 动态链接库DLL就是干这个的Python 负责业务逻辑、数据组织和界面C 负责算术、图像处理和底层硬件通信。这篇文章直接拆两个真实可跑的示例——整数相加和结构体传递把声明、编译、加载、传参、内存边界全部过一遍。适合刚接手跨语言调用任务的开发者也适合被 DLL 加载报错折磨过、想知道底层原因的人。我会把调用约定、extern C、ctypes 的 argtypes/restype 这些关键点一次讲透避免你走弯路。2. 第一个 DLL整数相加从 C 端声明到 Python 调用2.1 为什么需要 extern CC 名字修饰与导出表C 编译器为了支持函数重载会把函数名做“名字修饰”比如IntAdd经过编译后变成类似?IntAddYAHHHZ的符号名。Python 的 ctypes 在加载 DLL 时是按字符串去查找导出函数的它只知道你要找IntAdd不知道 C 修饰过后的名字所以根本找不到。解决方式就是给函数加 extern C告诉编译器这段代码按 C 语言的方式导出函数名保持原样。在示例一的 hello.h 里还有一套 EXPORT_HELLO_DLL 宏控制逻辑// hello.h #ifdef EXPORT_HELLO_DLL #define HELLO_API __declspec(dllexport) #else #define HELLO_API __declspec(dllimport) #endif extern C { HELLO_API int IntAdd(int a, int b); }当编译 DLL 时CPP 文件里定义了 EXPORT_HELLO_DLL所以 HELLO_API 展开为__declspec(dllexport)函数会被导出如果外部程序引用了这个头文件且没有定义 EXPORT_HELLO_DLL则展开为__declspec(dllimport)表示从外部 DLL 导入。这是一个通用的宏写法适合 Windows 下管理 DLL 导出不用删掉。2.2 编译搞清楚 __cdecl 与 __stdcall 的差别DLL 的导出函数有两种常见调用约定调用约定参数清理方Python 中的加载方式__cdecl调用方Pythoncdll.LoadLibrary__stdcall被调方DLLwindll.LoadLibrary示例一的工程默认使用 __cdecl所以 Python 端对应使用cdll.LoadLibrary(hello.dll)。如果 C 端编译时指定的是 __stdcall而 Python 端继续用 cdll程序运行时大概率会崩溃或报错。错误原因是参数栈的清理方式不匹配两边各管一半栈帧就乱了。在 VS 中创建 DLL 工程时默认情况是 __cdecl。如果要显式使用 __stdcall可以写extern C HELLO_API int __stdcall IntAdd(int a, int b);Python 端改用一个示例代码dll windll.LoadLibrary(hello.dll) ret dll.IntAdd(2, 4)选择哪一种本身没有优劣但工程里所有跨语言接口的调用约定必须一致。建议在头文件里直接写明#define CALL_CONV __cdecl或者__stdcall这样后续换编译配置时不会迷糊。2.3 Python 端加载与调用最小可运行代码把上面的 C 工程编译出 hello.dll 后写如下 Python 脚本from ctypes import * # 使用 cdll 加载 __cdecl 约定的动态链接库 dll cdll.LoadLibrary(hello.dll) ret dll.IntAdd(2, 4) print(ret)cdll.LoadLibrary返回一个 CDLL 实例通过dll.IntAdd获取函数对象再传两个整数参数调用。这段代码背后 ctypes 做了几件事根据函数名在 DLL 导出表里查地址、把 Python 的 int 自动转换为 C 的 int、按 __cdecl 约定调用函数、把 C 的 int 返回值转回 Python 的 int。整个过程被包装得很好看起来就像调用一个普通 Python 函数。这里最有迷惑性的一点是dll.IntAdd(2, 4)并没有显式声明参数类型。ctypes 默认假设参数是 C int所以对整数来说恰好匹配。但如果函数实际接收的是指针或者 double这个写法就会翻车得到荒谬结果或段错误。正确做法是给函数对象设置argtypes和restype这个习惯从最简单的例子就要养成dll.IntAdd.argtypes [c_int, c_int] dll.IntAdd.restype c_int ret dll.IntAdd(2, 4)设置后 ctypes 会做严格参数检查类型不匹配时提前抛异常而不是把垃圾数据传进 C 函数。所有 DLL 调用都应该显式声明这两项后面示例二会体现其必要性。2.4 尝试两个修正加载路径和返回类型cdll.LoadLibrary(hello.dll)有一个隐藏的风险系统会按默认搜索顺序查找 DLL包括当前目录、系统目录、PATH 环境变量等。如果你把 DLL 放在自定义目录这个写法会报“找不到指定的模块”。最稳妥的加载方式是使用绝对路径import os from ctypes import * dll_path os.path.join(os.path.dirname(os.path.abspath(__file__)), hello.dll) dll cdll.LoadLibrary(dll_path)路径中含中文或空格时没问题ctypes 支持但路径不能用相对路径“./hello.dll”在改变当前工作目录后就失效。实际的工程开发中我一般会先把 DLL 拷贝到 Python 脚本同目录再用上面的方式拼接路径省心很多。3. 传结构体字符串、数组和指针的边界问题3.1 C 端结构体与函数设计第二个示例的目标是C 端函数接收一个结构体指针往里面写入各种类型的数据——整数、char* 指针、定长 char 数组、int 数组——然后返回一个字符串。头文件定义如下// hello.h #define ARRAY_NUMBER 20 #define STR_LEN 20 struct StructTest { int number; char* pChar; char str[STR_LEN]; int iArray[ARRAY_NUMBER]; }; extern C { HELLO_API char* GetStructInfo(struct StructTest* pStruct); }对应实现文件// hello.cpp #include string.h #define EXPORT_HELLO_DLL #include hello.h HELLO_API char* GetStructInfo(struct StructTest* pStruct) { for (int i 0; i ARRAY_NUMBER; i) { pStruct-iArray[i] i; } pStruct-pChar hello python!; strcpy(pStruct-str, hello world!); pStruct-number 100; return just OK; }这个函数其实是在做一件事通过指针修改调用者传入的内存块。pStruct指向的内存由 Python 端分配C 端拿到地址后按结构体布局去写数据。这是跨语言编程最常见的模式——Python 负责分配C 负责填充。关键点是pStruct-pChar hello python!这一行。它把 pChar 指向了一个字符串字面量也就是静态存储区。这个字符串的生命周期是整个 DLL 加载期间在本例中可以安全使用。但如果后来改成char buffer[20]; strcpy(buffer, hello python!)再赋值给 pChar那就变成了指向函数栈上的数组函数返回后栈内存立刻失效Python 端读取到的将是未定义内容。后面避坑章节会详细展开。3.2 Python 端用 Structure 子类映射结构体Python 端需要构建一个与 C 结构体内存布局完全一致的类ctypes 提供了 Structure 基类from ctypes import * ARRAY_NUMBER 20 STR_LEN 20 INTARRAY20 c_int * ARRAY_NUMBER CHARARRAY20 c_char * STR_LEN class StructTest(Structure): _fields_ [ (number, c_int), (pChar, c_char_p), (str, CHARARRAY20), (iArray, INTARRAY20) ]布局必须与 C 端逐字段对齐number对应 C 的 intpChar对应 char* 指针str对应 char[20]iArray对应 int[20]。c_char * STR_LEN创建了一个长度为 20 的 char 数组类型c_int * ARRAY_NUMBER创建了长度为 20 的 int 数组类型两者都属于“定长数组类型”在字段中直接使用即可不需要先实例化。如果你的 C 结构体含有嵌套结构体或者联合体Python 端的字段写法是(sub_struct, SubStruct)或(union_data, UnionType)嵌套类型直接作为字段类型。ctypes 会自动计算嵌套布局的偏移和总大小。3.3 显式声明 argtypes 与 restype指针参数的正确写法现在加载 DLL 并调用函数dll cdll.LoadLibrary(hello.dll) GetStructInfo dll.GetStructInfo # 声明返回类型为 C char* 指针 GetStructInfo.restype c_char_p # 声明参数类型为 StructTest 结构体指针 GetStructInfo.argtypes [POINTER(StructTest)]如果没有POINTER(StructTest)ctypes 会把传入的参数默认当作 C int届时GetStructInfo(byref(objectStruct))传入的实际上是一个整数地址值函数内部按指针去访问行为完全不可控。显式声明 argtypes 后ctypes 会校验参数是否是合法的 Structure 实例并自动完成指针转换类型不匹配时直接抛 TypeError。创建结构体实例并调用objectStruct StructTest() retStr GetStructInfo(byref(objectStruct))byref(objectStruct)返回一个轻量级指针对象专门用于传给 C 函数。这里值得注意byref()和pointer()的区别在于byref()更快但只能用于函数调用的参数传递不能用于构建指针数组等场景如果要把结构体地址保存下来供后续使用则必须用pointer(objectStruct)。调用完成后验证数据print(number:, objectStruct.number) print(pChar:, objectStruct.pChar) print(str:, objectStruct.str) for i in range(ARRAY_NUMBER): print(Array[%d]: % i, objectStruct.iArray[i]) print(return:, retStr)objectStruct.str打印出来的类型是 bytes 而不是 str因为 c_char 数组对应 C 的 char 数组Python 端拿到的是字节串。需要在 Python 3 下用objectStruct.str.decode(utf-8)转换。pChar字段是 c_char_p 类型同样会返回 bytes也要做解码。3.4 结构体返回制的内存约束示例中函数返回类型是char*但字符串是函数内部返回的静态字面量。设置restype c_char_p是正确的因为 ctypes 会自动把 C char* 指针转换成 Python bytes 对象并在转换完成后放弃对原始指针的控制。如果函数的返回值是结构体本身而不是指针处理就完全不同了。例如 C 函数声明为struct StructTest GetStruct(),Python 端设置GetStruct.restype StructTest,ctypes 会拷贝整个结构体的内存块到 Python 对象。这种情况需要先设置argtypes []或留空且注意 C 端不能用__declspec(dllexport)导出 C 的类对象只能导出 POD 类型的结构体,否则涉及拷贝构造和所有权问题很容易崩溃。4. 避坑与常见问题排查跨语言调用翻车最多的五个点4.1 位数不匹配64 位 Python 加载 32 位 DLL现象cdll.LoadLibrary(hello.dll)抛出“OSError: [WinError 193] %1 不是有效的 Win32 应用程序”。原因进程位数和 DLL 位数不一致。64 位 Python 只能加载 64 位 DLL32 位 Python 只能加载 32 位 DLL。这一点在开发环境里特别容易混淆VS 默认生成 32 位 DLL 的工程配置Win32而 Python 安装的是 64 位版本两者直接就冲突。解决确认两边位数一致。在 Python 里运行import struct; print(struct.calcsize(P) * 8)查看当前解释器位数在 VS 的“配置管理器”里把活动解决方案平台改为 x64重新编译 DLL。还有另一个不易察觉的陷坑即使 Python 和 DLL 都是 64 位如果 DLL 依赖的某个第三方库还是 32 位加载时同样会报错。这时候需要检查 DLL 的依赖链用工具查看依赖列表逐一保证位数一致。4.2 字节对齐字段错位导致数据混乱现象Python 传入结构体后C 端读到的 number 是正确值但 iArray 里数据完全不对或者 str 字段出现乱码。原因C 编译器默认按结构体成员的最大对齐数对齐通常是 8 字节而 ctypes 在默认情况下也按 C 编译器规则对齐理论上不会出问题。但如果你在 C 端用了#pragma pack(1)或/Zp编译选项改变了对齐规则两边的布局就错位了。解决在 Python 端 Structure 子类中定义_pack_属性class StructTest(Structure): _pack_ 1 _fields_ [...]这里要注意一个细节当_pack_值与 C 端不一致时同样会错位。调试方法很简单在两边各打印结构体大小。C 端printf(%d\n, sizeof(StructTest))Python 端print(sizeof(StructTest))两者不一致说明布局有问题优先检查_pack_和编译选项。还有一种是字段顺序不一致导致偏移量对不上排查时逐字段打印字段偏移量StructTest.number.offset与 C 端 offsetof 对比。4.3 c_char_p 的生命周期陷阱现象调用函数后第一次读取 objectStruct.pChar 正常第二次再读就乱码或者程序直接崩溃。原因C 端代码把pChar指向了一个函数内部临时分配的内存比如char tmp[32]; sprintf(tmp, hello); pStruct-pChar tmp;函数返回后tmp 所在栈帧被回收内存内容随时可能被其他数据覆盖。Python 端访问这块已经是“悬空指针”的内存得到什么内容完全看运气。解决C 端不要返回局部栈内存的指针。要么返回静态字符串字面量如本示例要么用malloc分配内存并约定由调用方释放要么直接把内容拷贝到 Python 传入的 char 数组里。工程中最稳妥的方案是C 端不定义char*字段全部使用定长数组char str[128]Python 端对应c_char * 128调用方负责分配内存被调方只管向数组里写数据。这样内存所有权清晰不存在悬空指针的可能。4.4 DLL 搜索路径与依赖项缺失现象在 IDE 里能正常调用但把 Python 脚本和 DLL 拷贝到另一台机器后报“找不到指定的模块”或者加载时程序闪退无报错。原因Windows 加载 DLL 时有一个搜索顺序程序所在目录、系统目录、PATH 目录等。如果你的 hello.dll 依赖了其他 DLL比如 C 运行时库或第三方库那些依赖不在同目录或系统 PATH 中加载就会失败。很多时候报错提示的是“找不到 hello.dll”但实际上找不到的是它的依赖项误导排查方向。解决用绝对路径加载主 DLL同时把全部依赖 DLL 放在同一个目录下并把这个目录加到os.add_dll_directory()。在 Python 3.8 以上版本为了安全DLL 搜索路径受限需要显式声明import os os.add_dll_directory(rD:\work\libs) dll cdll.LoadLibrary(os.path.join(rD:\work\libs, hello.dll))有依赖项缺失时先确认所有依赖 DLL 是否都已拷贝完整。最直接的办法是使用依赖查看工具打开 hello.dll检查依赖树上的每个 DLL 是否存在于目标机器。4.5 回调函数与线程从 C 端回调 Python现象C 端在后台线程中调用 Python 传入的回调函数程序在回调代码处崩溃或表现随机。原因ctypes 默认允许回调但跨线程回调时没有持有 Python GIL 锁且回调函数内部如果访问了 Python 对象可能导致解释器状态不一致。解决创建回调函数时先获取 GIL 再执行from ctypes import CFUNCTYPE, c_int, pythonapi, PyDLL CFUNCTYPE(c_int, c_int) def callback_func(value): pythonapi.PyGILState_Ensure() # 此处执行 Python 逻辑 pythonapi.PyGILState_Release() return value使用PyDLL而不是CDLL加载含回调驱动逻辑的 DLL因为 PyDLL 在调用期间会保持 GIL。如果 C 端回调触发频繁对比在回调里加锁和直接操作 ctypes 内存的方式后者性能更高。这一条在示例中没有体现但真实项目中一旦涉及事件回调几乎必然碰到建议提前做好设计。5. 工程化封装把 ctypes 调用变成可维护的接口层ctypes 的调用方式是过程式的一个项目里有十几个 API 时散落各处的dll.LoadLibrary和argtypes赋值会让代码非常臃肿也很难做单元测试。常见的做法是封装成一个模块把 DLL 加载、类型声明、函数定义集中管理。第一步创建一个统一的加载器模块# dll_loader.py import os import ctypes class DllWrapper: def __init__(self, dll_path: str): self._dll ctypes.cdll.LoadLibrary(dll_path) def bind_function(self, name, argtypes, restype): func getattr(self._dll, name) func.argtypes argtypes func.restype restype return func调用方式# api.py from dll_loader import DllWrapper wrapper DllWrapper(rD:\work\libs\hello.dll) int_add wrapper.bind_function(IntAdd, [ctypes.c_int, ctypes.c_int], ctypes.c_int) get_struct_info wrapper.bind_function( GetStructInfo, [ctypes.POINTER(StructTest)], ctypes.c_char_p )这样每个 API 的参数和返回值类型集中声明未来排查类型问题时只看一处。异常处理也集中在这一层try: ret get_struct_info(ctypes.byref(obj)) except (OSError, ValueError, TypeError) as err: # 记录日志后抛出领域异常 raise RuntimeError(fDLL 调用失败: {err}) from errDLL 调用的错误不会直接是 Python 的ValueError而是“段错误”导致整个进程崩溃。要尽量在传入参数前做好类型检查不要在 C 端依赖错误提示。调试时还有一个技巧在 ctypes 的 CDLL 调用前用dll_name.in_dll(ctypes.pythonapi, PyObject)这类方式验证导出符号是否存在但这只适用于 Python C API 场景。对普通 DLL更实用的验证方法是对照工具——先查看系统日志再写一个小的 C/C 控制台程序调用同一个 DLL看是否能正常工作。如果 C 端调用正常、Python 端崩说明问题出在参数绑定或内存布局上重点查argtypes、restype和字段偏移如果 C 端调用也失败说明问题在 DLL 本身或依赖缺失跟 Python 无关。我一直在用的验证流程是先用一个小 C 程序调用 DLL 的全部导出函数确认 C 侧无误后再在 Python 里逐个对接。从封装到验证走完一遍后后续加新 API 只需要补一个绑定函数和一条测试用例省去了大量重复排查。这套方法现在已经成为我做跨语言调用的标准流程也希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
