根本原因是C++项目未正确配置Python的C API环境，需确保安装开发包、正确设置头文件路径和链接库、初始化解释器并管理GIL、处理引用计数、保证DLL可见性及运行时匹配。
Python.h 头文件找不到或编译失败
根本原因是 C++ 项目没连上 Python 的 C API 头文件和链接库，不是“调用方式不对”，而是环境没搭对。
- 确认已安装对应版本的
python3-dev（Ubuntu/Debian）或python3-devel（CentOS/RHEL），比如 Python 3.10 就要装python3.10-dev -
g++编译时必须显式加-I指向头文件路径（如/usr/include/python3.10），不能只靠#include <python.h></python.h> - 链接阶段漏掉
-lpython3.10或路径不对（-L/usr/lib/python3.10/config-3.10-x86_64-linux-gnu）会导致 undefined reference 错误 - Mac 上用
python3-config --includes和python3-config --ldflags获取准确参数，别硬写路径
Py_Initialize() 后 import 失败或 Segmentation Fault
Python 解释器启动了，但模块路径、运行时状态或线程环境没准备好，一 import 就崩。
- 调用
Py_Initialize()后必须立刻调用PyEval_InitThreads()（Python -
sys.path默认不包含当前目录，用PyRun_SimpleString("import sys; sys.path.insert(0, '.');")手动加，否则import mymodule找不到 - 避免在多线程 C++ 环境中反复调用
Py_Initialize()/Py_Finalize()：它不是线程安全的，且多次初始化会破坏内部状态 - 如果 Python 代码里用了
numpy或torch，确保这些包已在系统 Python 环境中 pip 安装，C++ 不会自动帮你装依赖
从 C++ 传字符串/数组给 Python 函数
不能直接把 std::string 或 std::vector<float></float> 塞进 Python，得转成对应的 PyObject*，否则内存越界或类型错误。
- 字符串用
PyUnicode_FromString()（UTF-8）或PyUnicode_FromWideChar()（wchar_t），别用PyBytes_FromString()除非你明确要 bytes - float 数组推荐用
PyArray_SimpleNewFromData()（需 NumPy C API），比手动构造 list 快且零拷贝；记得设置PyArray_ENABLE_CHECKING调试时捕获 shape/mem 错误 - 传完对象后注意引用计数：
Py_DECREF()掉临时创建的PyObject*，否则内存泄漏——尤其在循环中反复调用时 - Python 函数返回
None却当成有效对象解包，会触发SystemError: NULL object passed to Py_BuildValue
Windows 下 DLL 加载失败或找不到 python310.dll
不是代码问题，是动态链接时 runtime 找不到 Python 的 DLL，报错像 ImportError: DLL load failed while importing _ctypes 或直接 crash。
立即学习“Python免费学习笔记（深入）”；
- 确保
python310.dll（版本号按实际）在系统 PATH 中，或和你的 exe 放同一目录；不要只复制python3.dll（那是 stub） - Visual Studio 项目属性里，C/C++ → General → Additional Include Directories 填 Python 的
include路径，Linker → General → Additional Library Directories 填libs目录（不是Lib！） - Debug/Release 运行时必须匹配：Python 官方版是 MD（动态 CRT），你的 C++ 项目也得设成
/MD，设成/MT会因 CRT 冲突导致随机崩溃 - 用
dumpbin /dependents yourapp.exe检查是否真链接了python310.dll，而不是静态链接了 libpython
python3-config --ldflags 或 dumpbin 确认底层连接真实存在。 
