当前位置：首页 > news >正文

C++集成Python绘图库matplotlibcpp：配置、实战与独立发布指南

news 2026/7/24 8:25:34

1. 项目概述：为什么要在C++里集成Python的绘图库？

如果你是一个长期用C++做数值计算、仿真或者游戏开发的程序员，大概率对数据可视化这件事感到头疼。C++本身在计算性能上无可挑剔，但一到要画个曲线图、散点图或者热力图来展示结果的时候，就瞬间回到了“刀耕火种”的时代。要么去折腾那些庞大且复杂的原生图形库（比如Qt的Chart模块，或者更底层的OpenGL），要么就得把数据导出到文件，再用Python或MATLAB写个脚本画图，流程割裂，效率低下。

matplotlibcpp这个库的出现，就是为了解决这个痛点。它不是一个用C++重写的matplotlib，而是一个精巧的C++包装器（wrapper）。其核心思路是：利用C++调用Python的API（通过Python.h），让C++代码能够直接调用功能强大、生态成熟的Pythonmatplotlib库。这样一来，你可以在C++程序中，以近乎原生Pythonmatplotlib的语法进行绘图，生成高质量的PNG、PDF、SVG等格式的图片，或者甚至显示交互式窗口。这相当于把Python在科学绘图领域的“航母战斗群”，直接部署到了C++的“本土”上，实现了强强联合。

我最初接触这个库是在一个高性能物理仿真的项目中，我们需要实时监控迭代过程中关键参数的变化趋势。全部用Python写，性能瓶颈卡在循环计算上；全部用C++写，光搞个实时绘图界面就得多花几周。matplotlibcpp完美地折中了这两者：核心计算循环用C++保持极速，需要可视化时，直接在当前进程内调用matplotlib画图，数据零拷贝，流程无缝衔接。这次实战，我就带你从零开始，完成matplotlibcpp的完整配置，并最终解决一个更棘手的问题——如何将依赖Python环境的程序，打包成可以独立分发的可执行文件。

2. 环境准备与核心依赖解析

在开始敲代码之前，我们必须把地基打牢。matplotlibcpp的配置之所以让很多人望而却步，是因为它横跨了C++和Python两个生态，对系统环境有明确要求。配置过程的核心，就是让C++编译器能找到并正确链接Python。

2.1 系统与工具链选择

首先明确一点：matplotlibcpp高度依赖于你本地的Python环境。因此，你的C++项目必须和Python使用相同的“位数”（Architecture）。如果你的Python是64位的，那么你的C++编译也必须选择64位模式（例如，在Visual Studio中需选择x64平台），反之亦然。混合使用32位和64位是绝对无法成功的。

编译器方面：

Windows (Visual Studio)：这是最常用的环境。你需要安装Visual Studio（2017或更新版本），并确保在安装时勾选了“使用C++的桌面开发”工作负载，这会安装MSVC编译器。matplotlibcpp与MSVC兼容性很好。
Linux/macOS (GCC/Clang)：在类Unix系统上，通常使用GCC或Clang。你需要确保已安装Python开发头文件。在Ubuntu/Debian上，可以通过sudo apt-get install python3-dev来安装。macOS通过Homebrew安装Python后，一般会自带开发头文件。

Python环境：强烈建议使用Python 3.6及以上版本。matplotlibcpp的较新版本对Python 2的支持已经减弱。我个人习惯使用conda或venv创建独立的虚拟环境来管理项目依赖，这样可以避免污染系统Python环境，也便于依赖管理。确保你的虚拟环境中已经安装了numpy和matplotlib这两个核心库：

# 使用pip安装 pip install numpy matplotlib # 或者使用conda安装 conda install numpy matplotlib

2.2 获取matplotlibcpp库文件

matplotlibcpp本身非常轻量，它只有一个头文件：matplotlibcpp.h。你可以从它的GitHub仓库（https://github.com/lava/matplotlib-cpp）直接下载这个文件。这就是库的全部“代码”。它的工作原理是，在这个头文件里，通过Python.h提供的C API，将C++的函数调用和数据结构（主要是std::vector）转换并传递给Python端的matplotlib模块。

注意：直接使用官方的matplotlibcpp.h时，需要注意其Python.h的包含方式。在Windows+Visual Studio环境下，官方头文件默认的#include <Python.h>可能找不到路径。一个常见的做法是，在项目属性中设置好Python包含目录，或者临时修改头文件，使用绝对路径包含，例如#include “C:/Python39/include/Python.h”。不过，更规范的做法是通过项目配置来管理。

2.3 关键配置：让C++项目找到Python

这是配置环节最核心、最容易出错的一步。你需要告诉C++编译器两件事：1. Python的头文件在哪里；2. Python的库文件在哪里。

对于Visual Studio项目（以VS2022, Python 3.9安装在C:\Python39为例）：

打开项目属性：右键点击你的项目 -> “属性”。
配置包含目录：
- 进入C/C++->常规->附加包含目录。
- 添加你的Python安装路径下的include文件夹。例如：C:\Python39\include。
- 同时，也需要添加matplotlibcpp.h头文件所在的目录。
配置库目录：
- 进入链接器->常规->附加库目录。
- 添加你的Python安装路径下的libs文件夹。注意，这里是libs，不是Lib（后者是存放Python模块的）。例如：C:\Python39\libs。
配置链接库：
- 进入链接器->输入->附加依赖项。
- 添加需要链接的库文件名。对于Python 3.9，通常是python39.lib。这个文件就在上一步的libs文件夹里。请根据你的Python版本号进行修改（如python38.lib, python310.lib等）。

对于CMake项目：使用CMake可以更优雅地管理这些依赖。下面是一个简单的CMakeLists.txt示例，它使用find_package来定位Python：

cmake_minimum_required(VERSION 3.10) project(MatplotlibCppDemo) # 设置C++标准 set(CMAKE_CXX_STANDARD 11) # 查找Python解释器和发展组件（包括头文件和库） find_package(Python3 COMPONENTS Interpreter Development REQUIRED) # 添加可执行文件 add_executable(demo main.cpp) # 指定头文件包含路径 target_include_directories(demo PRIVATE ${Python3_INCLUDE_DIRS} # Python头文件路径 ${CMAKE_CURRENT_SOURCE_DIR}/path/to/matplotlibcpp # matplotlibcpp.h所在路径 ) # 指定链接库 target_link_libraries(demo PRIVATE ${Python3_LIBRARIES} # Python库文件 ) # 在Windows上，可能需要额外链接数学库（如sin, cos等函数） if(WIN32) target_link_libraries(demo PRIVATE m) endif()

这个CMake脚本会自动探测你系统中的Python3位置，并将正确的路径和库传递给编译器，省去了手动配置的麻烦，也提高了项目的可移植性。

3. 基础绘图功能上手与代码解析

环境配置妥当后，我们来写第一个“Hello World”级别的绘图程序，验证配置是否成功，并理解其基本用法。

3.1 一个简单的折线图示例

创建一个main.cpp文件，输入以下代码：

#include “matplotlibcpp.h” #include <vector> #include <cmath> namespace plt = matplotlibcpp; int main() { // 1. 准备数据 int n = 100; // 数据点数量 std::vector<double> x(n), y(n); for(int i=0; i<n; ++i) { x[i] = i * 0.1; // x从0到9.9 y[i] = std::sin(x[i]); // y = sin(x) } // 2. 绘图 plt::plot(x, y); // 3. 添加标签和标题 plt::xlabel(“X Axis”); plt::ylabel(“Y Axis”); plt::title(“Simple Sin Wave Plot using matplotlibcpp”); // 4. 显示网格 plt::grid(true); // 5. 显示图像（阻塞直到窗口关闭） plt::show(); // 或者，直接保存为图片（不显示窗口） // plt::save(“./sine_wave.png”); return 0; }

代码逐行解析与注意事项：

头文件与命名空间：包含matplotlibcpp.h，并为其定义一个简短的别名plt，这模仿了Python中import matplotlib.pyplot as plt的习惯，让代码看起来非常亲切。
数据准备：matplotlibcpp的核心数据接口是std::vector<double>。它内部会将这些向量数据转换为Python的list或numpy.ndarray。确保你的数据是double类型，或者至少是数值类型，matplotlibcpp的模板机制会处理一些基础类型的转换。
绘图函数：plt::plot(x, y)是最基本的绘图命令。它的行为几乎和Python里的plt.plot一致。你可以传入多个向量对来绘制多条线，例如plt::plot(x1, y1, x2, y2)。
标签与样式：xlabel,ylabel,title,grid这些函数的作用一目了然。matplotlibcpp支持大部分常见的pyplot样式函数。
show()与save()：
- plt::show()：这会弹出一个GUI窗口显示图像，并且会阻塞当前C++线程，直到你手动关闭窗口。这在需要交互查看时很有用，但在生成大量图片或服务器环境下可能不合适。
- plt::save(“filename.png”)：直接将图像保存到文件，不弹出窗口。这是生产环境更常用的方式，支持PNG、PDF、SVG等多种格式。重要提示：在同一个程序里，show()和多次save()可能会互相影响内部状态。一个良好的实践是，在每次save()之前调用plt::clf()清除当前图形，或者使用plt::figure()创建新的图形上下文。

编译与运行：使用配置好的Visual Studio直接编译运行，或者使用CMake构建：

mkdir build && cd build cmake .. cmake --build . --config Release ./demo (Linux/macOS) 或 .\Release\demo.exe (Windows)

如果一切顺利，你将看到一个显示正弦波的窗口，或者在当前目录下生成sine_wave.png图片。至此，基础集成已经成功。

3.2 进阶绘图：多子图、散点图与样式控制

matplotlibcpp的能力远不止画一条线。让我们看看如何实现更复杂的图表。

多子图（Subplots）： Python中常用的plt.subplots()在matplotlibcpp中可以通过plt::subplot(row, col, index)来模拟。

std::vector<double> t = linspace(0, 10, 100); std::vector<double> s1 = transform(t, [](double x){ return std::sin(x); }); std::vector<double> s2 = transform(t, [](double x){ return std::cos(x); }); std::vector<double> s3 = transform(t, [](double x){ return std::sin(x) * std::cos(x); }); plt::subplot(2, 2, 1); // 2行2列，第1个位置 plt::plot(t, s1); plt::title(“Sin(x)”); plt::subplot(2, 2, 2); plt::plot(t, s2, “r--”); // 红色虚线 plt::title(“Cos(x)”); plt::subplot(2, 2, 3); plt::plot(t, s3, “g:”); // 绿色点线 plt::title(“Sin(x)*Cos(x)”); plt::subplot(2, 2, 4); plt::scatter(s1, s2); // 散点图 plt::xlabel(“Sin(x)”); plt::ylabel(“Cos(x)”); plt::title(“Phase Plot”); plt::tight_layout(); // 自动调整子图间距，避免重叠 plt::save(“advanced_plots.png”);

关键点说明：

样式字符串：在plot函数中，你可以像Python一样传入第三个参数，一个格式字符串，如”r--“（红色虚线）、”g:“（绿色点线）、”b.-“（蓝色点划线）。这是matplotlib的经典语法。
scatter散点图：用法和plot类似，专门用于绘制散点。
tight_layout()：这是一个非常实用的函数，它能自动调整子图之间的间距和边距，让整个图面看起来更紧凑美观。在子图较多、标签较长时尤其有用。
数据生成：上面的linspace和transform是我为了方便写的辅助函数，你需要自己实现或使用C++标准库算法来生成数据。

直方图与图表标注：

// 生成一些随机数据 std::vector<double> data = generate_random_data(1000); plt::hist(data, 30, “skyblue”, “edgecolor”, “black”); // 绘制直方图，30个柱子 plt::xlabel(“Value”); plt::ylabel(“Frequency”); plt::title(“Data Distribution Histogram”); // 添加文本标注 plt::text(0.5, 0.9, “Mean: “ + std::to_string(calculate_mean(data)), {{“transform”, plt::gca()->transAxes}, {“fontsize”, 12}}); plt::save(“histogram.png”);

这里展示了hist函数的使用，以及如何使用text函数在图表特定位置（此处使用了相对坐标transAxes，即相对于坐标轴的比例位置）添加文本。plt::gca()用于获取当前坐标轴对象。

4. 独立发布实战：从“开发环境”到“用户电脑”

让程序在自己的电脑上运行只是第一步。真正的挑战在于，如何将你这个依赖了特定Python环境和matplotlib库的C++程序，打包成一个可以分发给其他用户（他们的电脑上可能根本没有Python，或者Python版本不对）的独立可执行文件。这是本项目“实战”二字的精髓所在。

4.1 发布困境与解决方案对比

你的C++程序在运行时，需要动态链接到python3X.dll（Windows）或libpython3.X.so（Linux），并且需要能找到matplotlib、numpy等Python包的安装位置。直接拷贝你的exe给别人，肯定会因为找不到这些依赖而崩溃。

常见解决方案有：

静态链接Python解释器：理论上最彻底，将Python解释器编译进你的exe。但Python本身并非为静态链接设计，过程极其复杂，且许可证（Python的PSF许可证）可能对静态链接分发有要求，不推荐。
依赖Python安装：要求用户电脑上预先安装指定版本的Python和pip包。这增加了部署复杂度，对用户不友好。
打包Python环境（推荐）：将程序依赖的最小化Python运行时环境（包括解释器、标准库以及项目用到的第三方包如numpy,matplotlib）一起打包，随你的程序一起分发。这是工业界常用的方案，在Windows上尤其成熟。

对于Windows平台，我们主要使用两种工具来实现方案3：PyInstaller（适用于打包纯Python脚本为exe）和手动封装。但我们的主角是C++程序，PyInstaller无法直接处理。因此，我们的策略是：将C++程序编译成exe，然后手动为其创建一个“便携式”的Python运行环境。

4.2 手动创建便携式Python运行环境（Windows）

假设我们的C++程序名为myplotter.exe，目标是在没有Python的电脑上运行它。

步骤一：确定依赖清单你的程序运行时，Python端需要以下模块：

Python解释器本身（python3X.dll和标准库）
numpy(matplotlib的强制依赖)
matplotlib及其依赖（如cycler,kiwisolver,pillow,pyparsing,python-dateutil,six等，具体版本依赖可通过pip show matplotlib查看）
matplotlib的后端（backend）。默认的GUI后端（如TkAgg）可能依赖额外的DLL（如tcl86t.dll,tk86t.dll）。为了简化，我们使用非交互式后端，例如Agg，它只负责生成图片文件，不弹出窗口，没有任何GUI依赖，最适合服务器或静默生成场景。

步骤二：准备“便携式”Python文件夹

在一台干净的开发机上，安装与你开发环境一致的Python版本（例如Python 3.9.13）。
使用pip install numpy matplotlib安装必要的包。
在你的项目输出目录（例如Release/）下，创建一个子文件夹，比如叫python_env。
将整个Python安装目录下的以下内容拷贝到python_env中：
- python39.dll（位于Python安装根目录或DLLs/子目录）
- python39.zip（标准库压缩包，可选，如果拷贝了Lib文件夹则不需要）
- Lib/文件夹（包含标准库和第三方包）。注意：这个文件夹很大（>100MB），我们可以精简它。只保留必要的：
  - site-packages/下的numpy,matplotlib, 以及它们依赖的包文件夹（如PIL对应pillow,dateutil等）。你可以通过反复测试运行，根据缺失模块的错误信息来逐步补充，或者使用工具如pip freeze列出所有依赖然后手动筛选。一个更粗暴但简单的方法是：先全部拷贝，然后逐步删除看似无关的包来缩小体积。
  - tkinter/（如果你使用TkAgg后端则需要，使用Agg则不需要）。
- DLLs/文件夹（可能包含一些必要的运行时库）。

步骤三：修改C++程序，设置Python路径关键的一步是，在C++程序初始化时（在调用任何matplotlibcpp函数之前），通过C API设置Python的模块搜索路径，让它指向我们便携式的python_env文件夹，而不是系统默认的路径。

#include <Python.h> // 需要直接包含Python.h #include “matplotlibcpp.h” #include <string> #include <iostream> namespace plt = matplotlibcpp; int main() { // —————— 关键代码开始：设置便携式Python路径 —————— std::wstring pythonHome = L”.\\python_env”; // 假设exe同级目录下有python_env文件夹 std::wstring pythonPath = pythonHome + L”;” + pythonHome + L”\\Lib;” + pythonHome + L”\\Lib\\site-packages”; // 设置Python主目录 Py_SetPythonHome(pythonHome.c_str()); // 初始化Python解释器 Py_Initialize(); if (!Py_IsInitialized()) { std::cerr << “Failed to initialize Python!” << std::endl; return -1; } // 将我们的路径添加到sys.path的最前面 std::string cmd = “import sys\n”; cmd += “sys.path.insert(0, r’” + std::string(pythonHome.begin(), pythonHome.end()) + “‘)\n”; cmd += “sys.path.insert(0, r’” + std::string(pythonHome.begin(), pythonHome.end()) + “\\\\Lib’)\n”; cmd += “sys.path.insert(0, r’” + std::string(pythonHome.begin(), pythonHome.end()) + “\\\\Lib\\\\site-packages’)\n”; // 强制使用’Agg’后端，避免GUI依赖 cmd += “import matplotlib\n”; cmd += “matplotlib.use(‘Agg’)\n”; // 必须在导入pyplot之前设置 PyRun_SimpleString(cmd.c_str()); // —————— 关键代码结束 —————— // 现在可以安全地使用matplotlibcpp了 std::vector<double> x = {1,2,3,4}; std::vector<double> y = {1,4,9,16}; plt::plot(x, y); plt::save(“output.png”); std::cout << “Plot saved to output.png” << std::endl; // 关闭Python解释器 Py_Finalize(); return 0; }

这段代码的要点和避坑指南：

Py_SetPythonHome：这行代码至关重要，它告诉Python解释器它的“家”在哪里，即标准库Lib等目录的根位置。路径必须是宽字符（wchar_t*）。
Py_Initialize：初始化解释器。必须在所有Python API调用之前执行。
修改sys.path：即使设置了PythonHome，第三方包（在site-packages）的路径也可能不会被自动加入。我们通过执行Python代码字符串，手动将我们的便携式环境路径插入到sys.path的最前面，确保优先从这里导入模块。
设置Matplotlib后端为’Agg’：’Agg’后端是一个非交互式后端，它使用Anti-Grain Geometry库将图形渲染到位图（如PNG）。它不依赖任何GUI工具库（如Tkinter, Qt），极大地简化了分发依赖。必须在import matplotlib.pyplot之前设置，通过PyRun_SimpleString执行matplotlib.use(‘Agg’)来实现。
路径分隔符：Windows路径中使用双反斜杠\\或原始字符串r”…”来避免转义问题。
Py_Finalize：程序结束时清理Python解释器。虽然现代操作系统会在进程退出时回收资源，但显式调用是个好习惯。

4.3 最终发布包结构

编译好修改后的C++程序，最终的发布目录结构应该类似于：

发布文件夹/ ├── myplotter.exe # 你的C++主程序 ├── python39.dll # Python解释器核心DLL ├── python_env/ # 便携式Python环境 │ ├── Lib/ │ │ ├── site-packages/ # 包含numpy, matplotlib等 │ │ └── ... (其他必要的标准库目录) │ └── DLLs/ # 可能需要的其他DLL └── 其他可能的运行时库 (如MSVC runtime DLLs)

现在，你可以将这个发布文件夹压缩成ZIP包，分发给任何Windows用户。他们只需要解压，双击myplotter.exe即可运行，无需安装Python。

重要提示：依赖的DLL：你的C++程序本身是用MSVC编译的，它可能依赖MSVCP140.dll,VCRUNTIME140.dll等运行时库。如果用户电脑上没有安装对应的Visual C++ Redistributable，程序依然会报错。解决方案有两个：1. 在安装说明中要求用户安装VC运行库；2. 使用静态链接运行时库的方式编译你的程序。在Visual Studio项目属性中，将C/C++->代码生成->运行时库设置为/MT（Release）或/MTd（Debug），这样运行时库会被静态打包进exe，增大文件体积但免除依赖。

5. 高级话题：性能优化与错误处理

将Python集成到C++中，性能和数据交换是需要仔细考虑的问题。此外，健壮的错误处理机制也必不可少。

5.1 性能考量：减少Python-C++边界穿越

每次在C++中调用plt::plot()，实际上都发生了一次从C++到Python的“边界穿越”（Boundary Crossing），这涉及到数据从std::vector到Python对象（如list或numpy.array）的转换和内存拷贝。对于大规模数据（例如百万级数据点），频繁的调用和转换会成为性能瓶颈。

优化策略：

批量操作：尽量避免在循环中多次调用绘图函数。一次性准备好所有数据，然后调用一次plt::plot绘制多条线，或者使用plt::subplot管理多个子图。
直接使用NumPy C API（进阶）：matplotlibcpp内部最终是将数据传给numpy数组。我们可以绕过matplotlibcpp的部分转换，直接在C++端创建numpy数组，然后传递给Python。这需要你熟悉NumPy的C API，代码会更复杂，但性能最优。matplotlibcpp的源码展示了如何将std::vector转为PyObject*，你可以借鉴其思路，直接操作PyArray_SimpleNewFromData来创建共享内存（或拷贝）的numpy数组。
```
// 伪代码示例：直接创建numpy数组 npy_intp dims[1] = {data.size()}; PyObject* py_array = PyArray_SimpleNewFromData(1, dims, NPY_DOUBLE, data.data()); // 然后将py_array传递给matplotlib函数（需要调用Python C API）
```
这种方法要求你更深入地介入Python C API的细节，并小心管理内存生命周期（谁负责释放data.data()的内存）。
使用更高效的后端：对于纯文件输出，Agg后端已经足够高效。如果涉及复杂交互或实时渲染，可能需要评估不同后端（如Qt5Agg,TkAgg）的性能，但这又会引入额外的依赖。

5.2 健壮的错误处理机制

当Python代码（包括matplotlib）在执行中发生错误时，默认情况下程序可能会直接崩溃或抛出难以理解的异常。我们需要在C++层捕获这些错误。

matplotlibcpp本身提供的错误处理比较有限。我们可以利用Python C API提供的错误检查机制。

#include <Python.h> #include “matplotlibcpp.h” #include <iostream> namespace plt = matplotlibcpp; bool run_python_code(const std::string& code) { PyObject* main_module = PyImport_AddModule(“__main__”); PyObject* global_dict = PyModule_GetDict(main_module); PyObject* result = PyRun_String(code.c_str(), Py_file_input, global_dict, global_dict); if (result == nullptr) { // 发生Python异常 PyErr_Print(); // 将错误信息打印到stderr PyErr_Clear(); // 清除错误状态，防止影响后续操作 return false; } Py_DECREF(result); return true; } int main() { // … 初始化Python (Py_SetPythonHome, Py_Initialize) … // 使用封装函数执行可能出错的代码 std::string setup_code = “import matplotlib\n” “matplotlib.use(‘Agg’)\n” “import matplotlib.pyplot as plt\n”; if (!run_python_code(setup_code)) { std::cerr << “Failed to setup matplotlib!” << std::endl; Py_Finalize(); return -1; } // 使用matplotlibcpp绘图，它内部也可能触发Python错误 try { std::vector<double> x, y; // … 准备数据 … plt::plot(x, y); plt::save(“plot.png”); } catch (const std::exception& e) { // matplotlibcpp可能会抛出C++异常包装Python错误 std::cerr << “Plotting failed: “ << e.what() << std::endl; // 也可以检查PyErr_Occurred() if (PyErr_Occurred()) { PyErr_Print(); PyErr_Clear(); } } Py_Finalize(); return 0; }

错误处理要点：

PyErr_Print()：将当前Python错误栈的信息打印到标准错误输出，对于调试非常有用。
PyErr_Clear()：清除当前的错误指示器。如果不清除，后续的Python调用可能会因为前一个错误而立即失败。
封装绘图操作：考虑将关键的绘图步骤封装在try-catch块中，并检查PyErr_Occurred()，可以让你在C++层面获得更友好的错误提示，而不是程序突然崩溃。
资源管理：使用Py_DECREF()正确管理Python对象的引用计数，防止内存泄漏。在简单的脚本式调用中（如PyRun_SimpleString），解释器通常会帮你管理，但在直接操作PyObject*时就必须小心。

6. 常见问题与排查技巧实录

在实际集成和发布过程中，你几乎一定会遇到下面这些问题。这里我把自己踩过的坑和解决方法记录下来，希望能帮你快速排雷。

6.1 编译期问题

问题1：fatal error C1083: 无法打开包括文件: “Python.h”: No such file or directory

原因：编译器找不到Python头文件。
解决：检查Visual Studio项目属性中C/C++->常规->附加包含目录是否正确添加了Python的include文件夹路径（如C:\Python39\include）。确保路径中使用的Python版本和位数（32/64）与你的项目配置完全一致。

问题2：LNK1104: 无法打开文件“python39.lib”

原因：链接器找不到Python的导入库。
解决：检查链接器->输入->附加依赖项中是否添加了正确的python39.lib（版本号可能不同），并检查链接器->常规->附加库目录是否指向了Python的libs文件夹。

问题3：error C2371: “_Py_NoneStruct”: 重定义；不同的基类型

原因：通常是因为以错误的顺序包含了头文件，或者在不同的编译单元中包含了不同版本的Python.h。
解决：确保在所有地方，#include <Python.h>都是第一个被包含的头文件（或者至少在包含任何可能冲突的系统头文件之前）。在matplotlibcpp.h中，它应该已经首先包含了Python.h，所以你的.cpp文件里直接#include “matplotlibcpp.h”即可，不要再单独包含Python.h，除非你有特殊需要。

6.2 运行期问题

问题4：程序启动时崩溃，提示无法定位程序输入点 Py_xxx 于动态链接库 python39.dll 上

原因：你链接的python39.lib和运行时加载的python39.dll版本不匹配。比如，你用Python 3.9.1的lib编译，但运行时环境里是Python 3.9.13的dll，或者反过来。
解决：保持开发、打包、部署环境中的Python小版本号完全一致。使用虚拟环境（如venv）固定版本，并将该环境下的dll和lib用于编译和打包。

问题5：运行时报错ModuleNotFoundError: No module named ‘matplotlib’或numpy

原因：Python解释器找不到这些第三方模块。在独立发布场景下，最常见的原因是sys.path没有正确设置到我们便携式的site-packages目录。
解决：
1. 确保Py_SetPythonHome设置的路径正确，且该路径下的Lib和Lib\site-packages结构完整。
2. 确保通过PyRun_SimpleString正确地将便携式环境的路径插入到了sys.path的最前面。
3. 检查便携式site-packages里是否确实存在matplotlib和numpy的文件夹。有时pip install可能会安装一些.dist-info目录，但主包文件夹可能因为权限问题缺失。

问题6：使用plt::show()时程序无响应或闪退

原因：GUI后端（如Tkinter, Qt）依赖的DLL缺失或版本不匹配。在便携式环境中，tcl86t.dll,tk86t.dll等文件可能没有正确拷贝，或者系统中缺少必要的运行时库（如MSVCRT）。
解决（推荐）：对于发布版本，放弃交互式显示，使用Agg后端并只使用plt::save()。如前文所述，在初始化时通过matplotlib.use(‘Agg’)强制设置。这样可以彻底摆脱对GUI库的依赖，使发布包更小、更稳定。如果必须使用GUI，则需要将对应后端的所有依赖DLL一并打包，并确保测试环境纯净。

问题7：保存的图片中文显示为方框（乱码）

原因：matplotlib的默认字体不包含中文字符。

解决：在绘图前，通过Python代码设置中文字体。你需要将一个中文字体文件（如simhei.ttf）打包到你的发布目录，并在代码中指定。

// 在初始化Python后，执行以下代码 std::string font_code = “import matplotlib\n” “from matplotlib import font_manager\n” “# 添加字体文件路径，假设字体文件在exe同级目录的’fonts’文件夹下\n” “font_path = ‘./fonts/simhei.ttf’\n” “font_prop = font_manager.FontProperties(fname=font_path)\n” “matplotlib.rcParams[‘font.sans-serif’] = [font_prop.get_name()]\n” “matplotlib.rcParams[‘axes.unicode_minus’] = False # 解决负号显示问题\n”; PyRun_SimpleString(font_code.c_str());

6.3 发布后体积优化

便携式Python环境动辄上百MB，主要是因为Lib文件夹和site-packages太大。可以尝试以下精简策略：

删除__pycache__目录：这些是字节码缓存，Python在运行时可以重新生成。
删除.pyc文件：同上。
精简标准库：删除一些肯定用不到的模块，如test,tkinter（如果不用）,idlelib,ensurepip,distutils等。此操作有风险，需谨慎测试。
精简site-packages：只保留numpy,matplotlib及其直接依赖包。numpy的core和lib子目录很大但通常必要。可以尝试用工具如pip-autoremove分析依赖，但手动测试是最可靠的方法：逐步删除包，直到程序运行报错，再把最后一个删掉的包加回来。
使用嵌入式Python分发：Python官方提供了“嵌入式”版本（Windows上是python-3.X.Y-embed-amd64.zip），它是一个极简的Python运行时，不包含标准库。你可以以此为基础，只添加你需要的标准库模块和第三方包，能最大程度减小体积。但配置起来更复杂，需要手动管理pythonXX._pth文件。