企业官网建设流程全解析

简介：这份整理教程面向需要在 Visual Studio 中集成 MATLAB 算法的 C++ 开发者与高校学生，重点解决 MATLAB 函数封装成 DLL 后如何在 VS 工程中正确引用、配置和调用的问题。压缩包共 1 个 docx 文件，约 1.08MB，内容以步骤说明、配置清单和代码片段组织，覆盖 MATLAB 打包 DLL、VS2017 包含目录与链接器依赖设置、mbuild 编译语言配置、C++ 测试程序骨架，以及 mwArray 参数传递和初始化、终止流程等关键环节。文档还给出可直接对照的调用格式、示例代码与参数说明，并整理常见排错思路，包含从 MATLAB 端封装到 VS 端测试的完整链路，说明测试程序中初始化、调用和资源释放的先后关系，便于读者复现混合编程流程，减少路径、库文件和运行时环境方面的试错成本。已有 2558 人学习或下载，适合希望快速上手 DLL 调用、查漏补缺的读者查阅。

1. 从头文件一加就报 LNK2019 说起：MATLAB 生成的 DLL 到 VS 之间还隔着两道门

算法在 MATLAB 里跑通了，要搬进 VS 的 C++ 工程——这是做信号处理、图像算法、控制仿真的团队几乎都会撞上的一堵墙。多数人的第一步是拿 deploytool 或 mcc 打出一个 dll，往工程里一扔，#include写上，编译过了，链接报 LNK2019，后面跟一串看不懂的修饰名；好不容易链接过了，程序连main都没进就静默退出。这不是玄学，是这条链路上本来就有三段彼此独立的东西：MATLAB 端的编译产物、VS 端的链接配置、运行期的 MATLAB Runtime。任意一段对不上，报错都会指向另外两段，让人反复误判。下面按我实际交付过的顺序，从.m一路讲到 Release 下能稳定跑。

2. 把 .m 编译成 DLL：mcc 的三段参数、五类产物与两个前置检查

2.1 先做可编译性体检：脚本改函数、动态调用补 pragma

MATLAB Compiler 只认函数，不认脚本。那种从头到尾一串赋值、中间plot一下、最后save一个文件的.m，直接扔给 mcc 会得到一句很模糊的报错。动手前先做两件事。

第一，把脚本包成函数，第一个返回值就是 C++ 侧能拿到的输出。哪怕原来只有一个结果，也要显式写function y = xxx(a, b)，不要靠ans。多个输出就写成[y1, y2] = xxx(a, b)，C++ 侧的nargout参数就是按这个顺序取。

第二，检查有没有绕过静态分析的调用。feval、str2func、函数句柄、回调、eval，这些 mcc 静态扫不出来，运行到那一行才会告诉你函数不存在。补的办法是在入口函数里加 pragma 注释：

function y = RunFilter(x, fs) % 入口函数：对输入序列做一次滤波并返回结果 %#function butter %#function filtfilt [b, a] = butter(4, 0.2); y = filtfilt(b, a, x); end

%#function后面跟函数名，一行一个，位置在函数体开头即可。它的作用是告诉编译器「这个函数会被动态调到，打包时别漏」，不写的话.ctf里就没有对应实现，运行期表现为「函数未定义」而不是编译报错，很难查。

还要留意工具箱限制：不是所有工具箱函数都支持编译，图形相关的figure、uifigure、交互式 App 基本不能进 DLL。算法里如果混了绘图或者input交互，先在外层砍掉，只保留纯计算部分。

2.2 用 mcc 生成 cpplib 的最小命令

确认.m干净之后，在 MATLAB 命令窗里跑：

% build_cpplib.m —— 放在入口 .m 同目录，直接在命令窗执行 mcc -W cpplib:libAddVec ... % cpplib: 后面是库名，不带扩展名，决定生成的头文件名 -T link:lib ... % 生成链接期需要的 .lib 与 .dll -d .\build ... % 输出目录，不存在会自动建 AddVec.m % 入口函数文件

三个参数各管一段：-W cpplib:libAddVec决定生成 C++ 接口（用mwArray那套类），如果写成-W lib:libAddVec生成的是 C 接口，函数签名里全是mxArray*，两边不能混用；-T link:lib决定产物形态是「能被别的程序链接的库」，不是独立 exe；-d只是输出位置，省掉就吐在当前目录。

想看得更细，加-v打印完整编译过程，包括 mcc 到底调了哪些中间文件。它第一次跑会慢，因为要初始化编译器，属于正常现象。

如果手上是较新版本，也可以用函数式写法，好处是产物路径能直接被脚本拿到：

% 新版函数式构建，返回值里带产物清单和日志路径 res = compiler.build.cppSharedLibrary('AddVec.m', ... 'OutputDirectory', 'build', ... 'LibraryName', 'libAddVec'); disp(res);

LibraryName就是最终 dll 的主名，OutputDirectory是相对当前路径的输出目录。两条路的产物是等价的，团队里统一一种写法就行，别一半脚本一半函数，后面维护会乱。

2.3 五类产物各管什么：h、lib、dll、ctf、exports

构建完目录里会多出一堆文件，第一次看容易懵。按用途归一下：

这里最容易翻车的是 ctf。它是加密归档，运行期第一次调用时会被解到临时目录下的mcrCache里，所以「第一次调用特别慢、后面就快了」不是性能问题，是解包。如果你手工把 dll 改名了但 ctf 没跟着改，运行时会打印找不到 CTF 的警告，函数返回全零——这种表现最坑，因为不崩，只是结果不对。

注意：不要手工重命名 ctf 去凑 dll 名字，直接用新的库名重新跑一遍 mcc，两边才会对齐。

2.4 位数与版本：两个必须在编译前确认的死条件

第一是位数。64 位 MATLAB 生成的必然是 64 位 DLL，VS 解决方案配置必须切到 x64。很多人默认新建工程是 Win32，编译能过（头文件不区分位数），链接阶段才炸。

第二是版本。生成的 DLL 绑死了编译它的那个 MATLAB 版本的 Runtime，主版本号跨了就不认。工程里如果有多个人，先统一「谁负责出 dll、用哪个版本」，别今天 A 用旧版出一份、明天 B 用新版覆盖，最后谁都跑不起来。

3. VS 工程挂接：三个路径、一个运行库、一份属性表

3.1 附加包含目录、附加库目录、附加依赖项怎么填

新建一个空 C++ 控制台工程，切到 x64，然后依次配三处。为了不让路径写死，先在属性管理器里建一个用户宏MATLAB_ROOT，值指向本机 MATLAB 安装根目录；后面所有路径都用$(MATLAB_ROOT)拼接，换机器只改一个地方。

• C/C++ → 常规 → 附加包含目录：$(MATLAB_ROOT)\extern\include
• 链接器 → 常规 → 附加库目录：$(MATLAB_ROOT)\extern\lib\win64\microsoft
• 链接器 → 输入 → 附加依赖项：libAddVec.lib;mclmcrrt.lib;

extern\include里放的是mclcppclass.h、mclmcr.h、matrix.h这些公共头，win64\microsoft里放的是对应的导入库。mclmcrrt.lib是运行时代理库，几乎所有导出符号最终都从它进。

如果代码里直接操作mxArray（比如自己造数组传给 C 接口），还得补libmx.lib;libmat.lib;。判断方法很简单：链接报错里出现mxCreateDoubleMatrix、mxGetPr之类没解析，就是缺这两个。别一上来全挂上，依赖项越多，后面换版本时越难定位。

3.2 把配置固化成 .props 属性表

一个团队里往往不止一个工程要调 MATLAB 的 dll，每个工程重配一遍路径，早晚有人漏一项。我一般做成属性表：视图 → 其他窗口 → 属性管理器，右键项目选「添加新项目属性表」，命名成MatlabDll.props，把上面三处全写进去，再让其他工程「添加现有属性表」引用它。

好处不只是省事。属性表进版本库之后，谁改了依赖项、谁加了库目录，diff 里看得清清楚楚，不会出现「我这儿能编你那儿不能编」的扯皮。

3.3 平台与运行库必须对齐：x64 与 /MD

位数说完，说运行库。MATLAB Runtime 是用/MD（动态链接 CRT）构建的，所以你的工程也必须用/MD。C/C++ → 代码生成 → 运行库，Release 选「多线程 DLL (/MD)」，Debug 选「多线程调试 DLL (/MDd)」。

选成/MT的后果是进程里存在两套 CRT 堆，mwArray在 Runtime 那边分配、在你这边析构，堆指针对不上，Release 下必崩，Debug 下因为调试堆的宽容度反而可能侥幸跑通——这就是「Debug 好好的，一上 Release 就挂」的典型来源。这类问题不看调用栈几乎查不出来，所以配置阶段就一次配对。

3.4 让程序启动时能找到 MATLAB Runtime

这一条是最容易忽略、也最容易被误判成「dll 坏了」的。

因为你链接了libAddVec.lib，Windows 会在进程启动、main还没执行的时候就去加载libAddVec.dll；而libAddVec.dll自己又依赖 Runtime 目录下的mclmcrrt*.dll。如果这个目录不在搜索路径里，进程直接以0xc0000135退出，连一行日志都不会给你。

走廊只有三条：

1. 把 Runtime 的runtime\win64目录加进系统 PATH。最省事，部署机上装完 Runtime 后写一次就行。
2. 延迟加载。链接器 → 输入 → 延迟加载的 DLL 填libAddVec.dll，这样加载时机推到第一次调用，你就有机会在main里先设路径。
3. 把 Runtime 的 dll 全拷到 exe 同目录。可行但目录会非常臃肿，不推荐。

采用第 2 条时，main里加这么一段：

#include <windows.h> #include <iostream> int main() { // 延迟加载模式下，这行必须在任何 libAddVec 符号被调用之前执行 if (!SetDllDirectoryA("D:\\MCR\\vXXX\\runtime\\win64")) { std::cerr << "SetDllDirectory failed: " << GetLastError() << std::endl; return -1; } // 之后才去调 libAddVecInitialize() return 0; }

SetDllDirectoryA的参数是本机 Runtime 的runtime\win64实际路径，vXXX换成安装目录里的真实版本号目录。它把该目录插到 DLL 搜索顺序里，优先级高于系统目录。注意这个函数会替换掉默认的搜索目录集合，所以如果你的程序还依赖别的自建 dll 目录，得用AddDllDirectory配合LoadLibraryEx，别图省事一把梭。

4. 调用姿势：mwArray 传参、多输出与列优先存储

4.1 一个完整的向量相加调用

先看入口函数。假设AddVec.m内容是两个同维向量逐元素相加，C++ 侧要拿到结果向量：

function y = AddVec(a, b) % 两路同维向量逐元素相加 y = a + b; end

编译后，libAddVec.h里跟调用相关的部分大致是这样（节选，宏名以实际生成为准）：

extern LIB_libAddVec_CPP_API void MW_CALL_CONV AddVec(int nargout, mwArray& y, const mwArray& a, const mwArray& b); extern LIB_libAddVec_CPP_API bool MW_CALL_CONV libAddVecInitialize(void); extern LIB_libAddVec_CPP_API void MW_CALL_CONV libAddVecTerminate(void);

规律很固定：第一个int是要几个输出，接着是所有输出（引用），再接着是所有输入（常量引用）。输入输出顺序和 MATLAB 函数签名一一对应，不会乱。

对应的 C++ 调用：

#include <iostream> #include <vector> #include "libAddVec.h" int main() { if (!libAddVecInitialize()) { // 启动 Runtime，同时解包 ctf std::cerr << "libAddVecInitialize failed" << std::endl; return -1; } const int n = 3; double a[n] = {1.0, 2.0, 3.0}; double b[n] = {4.0, 5.0, 6.0}; mwArray mA(1, n, mxDOUBLE_CLASS, mxREAL); // 行数、列数、类型、实/复 mwArray mB(1, n, mxDOUBLE_CLASS, mxREAL); mA.SetData(a, n); // 按列优先顺序灌入 mB.SetData(b, n); mwArray mY; // 输出不用预分配 AddVec(1, mY, mA, mB); // 1 表示要 1 个输出 std::vector<double> y(n); mY.GetData(y.data(), n); for (int i = 0; i < n; ++i) std::cout << y[i] << " "; std::cout << std::endl; libAddVecTerminate(); return 0; }

几个参数值得掰开说。mwArray(1, n, mxDOUBLE_CLASS, mxREAL)四个参数分别是行、列、元素类型、是否复数。MATLAB 里所有标量本质都是 1×1 矩阵，所以传单个 double 也写成mwArray(1, 1, mxDOUBLE_CLASS, mxREAL)，不要想着有专门的标量类型。

SetData(ptr, len)的len是元素个数，不是字节数。类型不匹配它不会帮你转，mxDOUBLE_CLASS的数组硬塞float*进去，读到的是一片垃圾，且不报错。

AddVec(1, mY, mA, mB)里那个1是nargout。如果入口函数只声明了一个返回值，这里传 1 就对；传 2 会抛异常，因为函数根本没有第二个输出槽。

4.2 多输出与标量返回值怎么接

多输出的入口函数长这样：

function [big, pos] = FindMax(x) % 返回最大值及其位置 [big, pos] = max(x); end

C++ 侧就按顺序接：

mwArray mX(1, 5, mxDOUBLE_CLASS, mxREAL); double xv[5] = {3.0, 9.0, 2.0, 7.0, 5.0}; mX.SetData(xv, 5); mwArray big, pos; FindMax(2, big, pos, mX); // nargout = 2 double maxVal = (double)big; // 单元素直接强转，省去 GetData int maxIdx = (int)pos; std::cout << maxVal << " at " << maxIdx << std::endl;

mwArray提供了operator double()和operator int()，取单元素时比走一遍GetData干净。但只在确认尺寸是 1×1 的时候用，2×3 的矩阵强转只会拿到第一个元素，剩下的悄悄丢掉，这是很隐蔽的一类错误。

另外pos拿到的是 MATLAB 的 1-based 下标。要喂回 C++ 数组记得减一，这种 off-by-one 在联调阶段能耗掉半天。

4.3 矩阵维度：MATLAB 的列优先会让你的图转 90 度

MATLAB 内部是列优先存储，mwArray::SetData和GetData也遵循这个顺序。而 C++ 里惯用的二维数组是行优先。直接把double[6]灌进 2×3 的mwArray，得到的是转置后的矩阵。

正确做法是自己转一次：

// C 侧 row-major：[1,2,3; 4,5,6] 摊平成 1,2,3,4,5,6 double rowMajor[6] = {1, 2, 3, 4, 5, 6}; double colMajor[6]; for (int r = 0; r < 2; ++r) for (int c = 0; c < 3; ++c) colMajor[c * 2 + r] = rowMajor[r * 3 + c]; // 行优先 -> 列优先 mwArray M(2, 3, mxDOUBLE_CLASS, mxREAL); M.SetData(colMajor, 6);

图像处理里这个坑出现频率极高。一张H×W的图按行存进mwArray(H, W, ...)，MATLAB 那边看到的其实是转置图，滤波结果出来再转回去，如果漏转一次，整张图就是斜的——而且肉眼一看还挺像那么回事，容易漏检。建议在封装层入口统一做一次转换，绝不让裸指针直接进SetData。

4.4 用 RAII 把 Initialize / Terminate 管起来

libAddVecInitialize()一个进程只能调一次，libAddVecTerminate()之后所有mwArray都失效。手写配对很容易在异常分支上漏掉，我一般包一个守卫类：

class MwRuntimeGuard { public: MwRuntimeGuard() { ok_ = libAddVecInitialize() != 0; if (!ok_) std::cerr << "MCR 初始化失败" << std::endl; } ~MwRuntimeGuard() { if (ok_) libAddVecTerminate(); } MwRuntimeGuard(const MwRuntimeGuard&) = delete; MwRuntimeGuard& operator=(const MwRuntimeGuard&) = delete; bool ok() const { return ok_; } private: bool ok_; };

在main开头声明一个栈上对象，函数怎么退出都会走到析构。拷贝构造和赋值显式删掉，是因为 Runtime 的初始化是进程级的，复制一份守卫对象会导致Terminate被调两次，第二次直接访问违例。多线程场景下，守卫对象本身不用加锁，但要保证只有一个线程去构造它——最省事的做法是在程序启动阶段建好，后面所有工作线程只读。

5. 避坑与排查：五类在初始化阶段就翻车的现场

5.1 双击 exe 弹「丢失 libAddVec.dll」

现象：编译链接全过，双击运行时系统弹窗说找不到 dll，错误码0xc0000135，日志一个字都没有。

原因是 DLL 在进程启动阶段就被加载，此时main还没跑，你在main里写的SetDllDirectory或者任何路径设置都来不及生效。它要的不只是libAddVec.dll本身，还有它依赖的mclmcrrt*.dll。

解决有两条路：把 Runtime 的runtime\win64加进系统 PATH 并重启 IDE（环境变量对已启动的进程不生效）；或者在链接器里把libAddVec.dll设为延迟加载，加载时机推到第一次 API 调用。

5.2 Initialize 返回 false 或直接访问违例

现象：libAddVecInitialize()返回 0，控制台没更多信息；或者干脆在调用点崩掉。

九成是 Runtime 版本对不上。DLL 是哪个 MATLAB 版本出的，目标机就必须装那个版本对应的 Runtime，主版本跨了不认。位数也要一致，64 位 dll 配 32 位 Runtime 一样起不来。

排查动作：确认目标机上 Runtime 安装目录的版本号，和生成 dll 的 MATLAB 版本逐个字符比。别指望「装个新的向下兼容」，这条路上没有后悔药。

5.3 目录里明明躺着 ctf，运行时还报找不到

现象：控制台打印一行 CTF 相关的警告，函数能进去但返回全零或空数组。

原因是 ctf 和 dll 的名字必须严格一致。有人为了版本管理把 dll 改名成libAddVec_v2.dll，ctf 没动，运行时按 dll 名去找libAddVec_v2.ctf，自然找不到。还有一种情况是 ctf 被放到了子目录，运行时只认 dll 同目录。

解决：不手工改名，用新库名重新跑 mcc；部署脚本里把 dll 和 ctf 成对拷，别只拷 dll。

5.4 LNK2019 找不到入口函数符号

现象：链接报错里出现一长串修饰名，类似?AddVec@@YAXHAAVmwArray@@ABV1@0@Z，看着像 C++ 名字修饰问题。

实际原因常常是位数不匹配：x64 的工程挂了win32目录下的 lib。头文件不区分位数，所以编译期毫无征兆，只在链接暴露。

排查顺序：先看配置管理器里解决方案平台是不是 x64；再看附加库目录是不是extern\lib\win64\microsoft；最后确认libAddVec.lib确实是刚才那次 mcc 出的，不是从别处拷来的旧文件。

5.5 Debug 正常、Release 必崩

现象：Debug 下跑一百遍都对，切 Release 断在mwArray析构或者Terminate附近，调用栈指向堆操作。

原因是运行库混用。工程用了/MT静态链接 CRT，而 Runtime 是/MD构建的，进程里存在两套堆，跨堆释放必然出错。Debug 下调试堆有一定的容错，把问题掩盖了。

解决：C/C++ → 代码生成 → 运行库，Release 明确选「多线程 DLL (/MD)」。同时检查有没有第三方静态库是/MT编的，混进来一样会出事。

6. 把 DLL 收进一层封装：黄金用例、初始化时机与部署清单

在工程里裸调mwArray调上三个月，代码会变得没法看——每个业务函数里都掺着SetData、GetData、维度转换。我后来的做法是收敛出一层薄封装，对外只暴露std::vector<double>或者项目自己的矩阵类型，mwArray一律不出现在业务代码里。

// 对外只暴露普通容器，mwArray 的生命周期全封在函数内部 std::vector<double> AddVec(const std::vector<double>& a, const std::vector<double>& b) { mwArray ma(1, static_cast<int>(a.size()), mxDOUBLE_CLASS, mxREAL); mwArray mb(1, static_cast<int>(b.size()), mxDOUBLE_CLASS, mxREAL); ma.SetData(a.data(), static_cast<int>(a.size())); mb.SetData(b.data(), static_cast<int>(b.size())); mwArray my; AddVec_cpp(1, my, ma, mb); // 实际入口名以生成的头文件为准 std::vector<double> out(a.size()); my.GetData(out.data(), static_cast<int>(a.size())); return out; }

这一层里还顺手挡住两个东西：尺寸校验和异常转换。a.size() != b.size()时直接抛std::invalid_argument，别等 MATLAB 那边报错再反查；mwArray抛出的异常统一 catch 成项目自己的错误码，否则上层根本不知道发生了什么。

验证靠黄金用例，不靠肉眼。同一批输入，MATLAB 侧直接跑一遍存成ref.csv，C++ 侧跑完存cpp_out.csv，用一个几行的脚本比对：

import numpy as np ref = np.loadtxt("ref.csv", delimiter=",") got = np.loadtxt("cpp_out.csv", delimiter=",") assert ref.shape == got.shape, f"shape mismatch: {ref.shape} vs {got.shape}" err = np.max(np.abs(ref - got)) print("max abs err =", err) assert err < 1e-10, "结果偏差超出容差"

容差别拍脑袋定成 1e-6，双精度浮点在不同 BLAS 实现下差异比想象中小，1e-10 通常够用；如果某次突然超了，多半是输入没对齐或者列优先转换漏了，而不是数值精度问题。这套用例我一般会建五到十组，覆盖空输入、单元素、大矩阵、含 NaN 这几种边界，每次换 MATLAB 版本或者升级 Runtime 都跑一遍，比事后查线上问题便宜太多。

初始化时机也有讲究。libAddVecInitialize()不要放在每个业务函数里，包一层进程级单例，第一次用到时初始化，退出时统一Terminate。有人图省事每次调用前后各来一次，单次调用看不出问题，压测跑到几百 QPS 就开始随机崩——初始化会去解 ctf、加载 Runtime，反复做等于反复折腾进程状态。

部署清单我贴在工程 README 里，三行：目标机装对应版本、对应位数的 Runtime；exe 目录放libAddVec.dll加libAddVec.ctf，成对出现；PATH 里包含 Runtime 的runtime\win64。这三条有任何一条不满足，前面所有代码都白写。

这套东西我从第一次被 LNK2019 按在地上摩擦，到现在能在一个下午内把一个新算法接进 VS 工程，中间踩的坑基本都在这几条上。真要给一句经验：先把这三行部署清单在目标机上验证通，再回头看代码——顺序反了，你会在一个根本不属于代码的问题上耗掉两天。希望帮到你。

本文还有配套的精品资源，点击获取