企业官网建设流程全解析

手上有个 C# 写的上位机，算法部分却只能用 C++——这种活我接过不少。要么是硬件厂商只给了 C++ 的 SDK，要么是性能敏感的图像处理、信号解算必须走原生代码，要么是十几年前的老库里全是 C++ 实现，重写成本高得离谱。这时候绕不开一件事：把 C++ 编译成 DLL，再让 C# 去调。听起来就是DllImport加个extern的事，真上手你会发现坑是一层叠一层的：函数名找不到、进函数就崩、传个结构体数据全乱、调试器根本不进 C++ 代码。这些问题不是靠搜索能一次解决的，得先把整条调用链的原理搞清楚。这篇内容适合刚接触 P/Invoke 的 C# 开发者，也适合那些写了多年 C++ 却总被托管侧同事追问"你这个 DLL 怎么调不了"的老手，里面每一段都是实际项目里试出来的结论。

1. 先想清楚：这条调用链到底长什么样

1.1 从托管到非托管，中间隔了什么

很多人在写[DllImport]的时候，脑子里默认它是"直接调用"，其实中间隔了一整套机制。CLR 在第一次碰到这个声明时，会去加载目标 DLL，在导出表里找符号，然后按照声明的调用约定和参数类型，一块一块地把托管内存里的数据翻译成非托管格式，压到栈上或者塞进寄存器，跳过去执行，返回时再把结果翻译回来。这个翻译过程就是封送（Marshaling），它是有成本的，也是有规则的。

理解这一点很重要，因为你后面遇到的绝大多数问题，本质上都是"我以为它会自动转，结果它转的方式和我想的不一样"。比如bool在 C# 里是 1 字节，但 Windows 原生代码里习惯用的BOOL是 4 字节，封送器默认按 4 字节处理，你的 C++ 函数签名写的是 1 字节的bool，两边就对不上了。再比如字符串，C# 的string是 UTF-16，C++ 的char*可能是 ANSI 也可能是 UTF-8，封送器默认按 ANSI 处理，中文就变成乱码。

我一般会把这条链拆成四个环节来检查：加载（DLL 能不能找到、位数对不对）、查符号（导出名是不是完全匹配）、封送（参数类型和内存布局是否一致）、执行（调用约定是否匹配、异常是否被拦住）。四个环节任何一环出问题，表现都不一样，学会区分就能少走很多弯路。

1.2 三种导出形态的取舍

C++ 侧想把功能暴露出去，理论上不止一种做法，我把自己用过的三种摆出来对比一下。

结论很直接：新项目一律走 C 风格函数导出。原因不是它先进，而是它足够笨。笨的东西没有隐藏行为，出问题容易定位。导出 C++ 类这条路，很多人试过，最后都卡在"我能导出，但 C# 那边接不住"上。C++ 的类在二进制层面包含虚函数表指针、名字修饰、构造函数调用约定等一堆东西，DllImport只认函数符号，它不知道什么叫对象。

至于 C++/CLI，它确实好用，写个ref class就能被 C# 直接引用，但它的限制也很明确：只能在 Windows 上跑，必须在项目属性里打开/clr，编译出来的混合程序集在某些加载场景下会有额外麻烦。如果你手上是 .NET Framework 的老项目，C++/CLI 是个不错的选择；如果是 .NET 6 以上的新项目，虽然 Windows 上仍然支持，但我更倾向于老老实实写 C 接口，因为它的心智负担最小。

1.3 调用约定与名字修饰：九成的报错源头在这里

这两个概念必须放在一起讲，因为它们共同决定了"你的函数在 DLL 里到底叫什么名字"。

名字修饰分两层。第一层是 C++ 编译器为了支持函数重载，会把参数类型编进符号名里，比如int Add(int,int)可能被修饰成?Add@@YAHHH@Z这种鬼东西。extern "C"的作用就是关掉这一层修饰，让符号名保持为Add。

第二层修饰跟调用约定有关，而且在 32 位和 64 位下表现完全不同：

• 32 位（x86）：__cdecl会加下划线前缀，变成_Add；__stdcall会变成_Add@8（@后面是参数占用的字节数）。注意，extern "C"管不了这一层。
• 64 位（x64）：微软的 x64 ABI 只保留一种调用约定，__cdecl和__stdcall写上去编译器都接受但实际行为一样，而且符号名不加任何前后缀，就是干干净净的Add。

这就是为什么同一份代码，32 位编译能跑，64 位编译就报EntryPointNotFoundException——反过来了，通常是 32 位下名字对不上。

C# 这边的默认值也容易踩坑。[DllImport]在不写CallingConvention时，默认是Winapi，在 Windows 平台上等价于StdCall。所以如果你的 C++ 函数是__cdecl（这是 C/C++ 的默认值），而 C# 声明里没写，两边就错配了。在 x86 下，调用约定不匹配的后果是栈不平衡：调用方和被调用方对"谁来清理栈"的认知不同，函数返回后栈指针偏移，轻则后面几个变量的值莫名其妙变了，重则直接访问违例。

提示：如果你不想在这上面反复纠结，最省事的做法是 C++ 侧统一写__stdcall，C# 侧统一写CallingConvention.StdCall，两边对齐，然后 32/64 位都能跑。唯一要注意的是 x86 下导出名会带@N后缀，用.def文件可以绕过去，后面会讲。

2. 接口设计：把坑提前埋掉

2.1 导出函数一律走 C 风格

我给自己定了一条铁律：凡是给托管代码调的导出函数，一律写在extern "C"块里。这不是风格问题，是能不能用的问题。

// image_proc.h #pragma once #ifdef IMAGEPROC_EXPORTS #define IMAGEPROC_API __declspec(dllexport) #else #define IMAGEPROC_API __declspec(dllimport) #endif #define IMAGEPROC_CALL __stdcall extern "C" { IMAGEPROC_API int IMAGEPROC_CALL ProcInit(void); IMAGEPROC_API int IMAGEPROC_CALL ProcProcess( const unsigned char* src, int width, int height, unsigned char* dst, int* outLen); IMAGEPROC_API int IMAGEPROC_CALL ProcGetLastError(char* buf, int bufSize); }

这段头文件里有几个细节值得说。IMAGEPROC_API这个宏是双面的：编译 DLL 本身时定义IMAGEPROC_EXPORTS，宏展开成dllexport；C# 那边当然不用这个头文件，但如果将来有别的 C++ 模块要静态链接进来，dllimport分支就有用了。这是一个很常见的工程习惯，不算多余。

所有函数返回int作为错误码，而不是用返回值传数据。原因是：跨语言边界传递复杂返回值是最容易出问题的地方，尤其是字符串和对象。用错误码 + 输出参数的模式，C# 侧拿到的是明确的成功/失败信号，数据通过调用方提供的缓冲区回填，内存归属清晰，出问题也容易定位。

还有一个细节：ProcGetLastError让调用方传缓冲区进来，而不是返回内部静态指针。有人喜欢写const char* GetVersion()直接返回常量字符串，这个是可以的，因为常量字符串的生命周期是永久的，C# 用string接、CharSet.Ansi封送，它会拷贝一份，没问题。但如果是动态拼接的错误信息，返回内部static缓冲区就有线程安全问题了，而且下次调用会覆盖上一次的内容，用起来很别扭。

2.2 用 .def 文件接管导出名单

__declspec(dllexport)够用，但它有个副作用：导出名受调用约定影响。在 x86 下，__stdcall的函数导出名会变成_ProcInit@0，C# 那边如果不写EntryPoint就找不到。解决办法有两个，我推荐第二个。

第一个办法是在 C# 的属性里显式指定：

[DllImport("imageproc", EntryPoint = "_ProcInit@0", CallingConvention = CallingConvention.StdCall)] public static extern int ProcInit();

能用，但很难看，而且换个编译配置（比如换成 x64）后缀就没了，代码得跟着改。

第二个办法是在工程里加一个.def文件，显式列出导出名：

LIBRARY ImageProc EXPORTS ProcInit ProcProcess ProcGetLastError

然后在项目属性里把"模块定义文件"指向它。这样一来，不管 32 位还是 64 位、不管什么调用约定，导出名永远是你写的那个名字，干干净净。这个做法还有一个附带好处：你可以精确控制哪些符号被导出。大型 C++ 项目里，dllexport到处撒容易把内部符号也暴露出去，.def文件相当于一份白名单，谁该出去一目了然。

.def文件里的@序号写法（比如ProcInit @1）可以进一步固定导出序号，但这玩意一旦发布就不能改顺序，否则老版本调用方全部失效。我一般不用序号，只用名字，可读性更好，也不怕后期加函数。

2.3 类型映射表与结构体对齐

这是最容易出错、也最需要背下来的一块。C++ 和 C# 的类型系统不是一一对应的，封送器有一套自己的默认规则，你必须知道它默认怎么转，才能判断什么时候需要手工干预。

关于bool，我要多啰嗦两句，因为这是新手翻车率最高的地方。C++ 的bool标准上是 1 字节，Windows API 里的BOOL是int的别名、4 字节。C# 的bool在托管内存里是 1 字节，但封送器默认把它按 4 字节的BOOL处理。如果你的 C++ 函数签名是bool Check(...)，参数或返回值就会被错位读取。解决办法只有两个：加[MarshalAs(UnmanagedType.I1)]明确告诉封送器"这是 1 字节"，或者干脆在 C++ 侧把接口里的bool全换成int。我个人倾向后者，接口层面少一点类型歧义，跨语言的兼容性更好。

结构体对齐是另一个隐形杀手。C++ 默认按成员中最大对齐值来排布，C# 的LayoutKind.Sequential默认也是自然对齐，多数情况下能对上。但如果你的 C++ 结构体前面有#pragma pack(1)或者#pragma pack(push, 4)，那就必须告诉 C#：

[StructLayout(LayoutKind.Sequential, Pack = 1)] public struct FrameInfo { public int Width; public int Height; public byte Channels; public long Timestamp; }

Pack = 1对应#pragma pack(1)。这个参数不写，C# 会按自然对齐补空洞，字段偏移全错。判断方法很简单：在 C++ 侧用offsetof把每个成员的偏移打出来，在 C# 侧用Marshal.OffsetOf对一遍，对不上就是对齐问题。这个自检我建议在联调第一天就做，比事后猜字段错位高效得多。

2.4 字符串、数组、回调的传递约定

字符串走三条路，各有各的适用场景。

第一条是调用方传缓冲区，DLL 往里填。头文件里ProcGetLastError(char* buf, int bufSize)就是这种。C# 侧可以用StringBuilder接：

var sb = new StringBuilder(256); NativeMethods.ProcGetLastError(sb, sb.Capacity); string err = sb.ToString();

注意StringBuilder必须指定容量，默认容量是 16，DLL 往里写超过 16 个字符就越界了。而且 DLL 里必须严格遵守bufSize，写完要补\0，否则ToString()会一直读到野内存。

第二条是 DLL 返回常量字符串，C# 用string接，CharSet.Ansi或者CharSet.Unicode按实际编码选。这条路简单，但只能用于生命周期是永久的字符串。

第三条是 DLL 分配内存返回指针，C# 用IntPtr接，转完字符串后必须调用 DLL 提供的释放函数。绝对不能用Marshal.FreeHGlobal去释放 C++new出来的内存，两边用的堆不一样，这么干必然崩溃。这条规则我见过太多人违反，后面还会专门讲。

数组的处理相对直接，传指针 + 长度就行。C# 侧用byte[]，P/Invoke 会自动把数组 pin 住（固定住不让 GC 移动），调用期间指针有效。但要注意：这个指针在函数返回后就失效了，C++ 侧不能把它保存到全局变量里下次再用。如果确实需要长期持有，得在 C++ 侧拷贝一份。

回调是最需要小心的。C# 传委托给 C++，封送器会生成一个函数指针，但这个委托对象本身在托管堆上，如果没有强引用，GC 随时可能把它回收掉。一旦被回收，C++ 那边再回调就是一针野指针。解决办法是把委托保存在一个静态字段里，或者用GCHandle.Alloc固定住。这个细节比想象中重要，因为这种崩溃是不定时的，测试环境跑一天没事，现场跑两周崩一次，排查成本极高。

2.5 内存归属：谁申请谁释放

这是整篇文章里我最想强调的一条原则：内存在哪边申请的，就由哪边释放，绝不交叉。

C++ 的new/malloc和 C# 的Marshal.AllocHGlobal用的是完全不同的分配器，底层堆不一样。你在这边申请的内存，拿到那边去释放，等于拿着 A 家银行的存折去 B 家银行取钱，行为未定义。表现出来就是各种诡异的堆损坏异常，而且位置和时机都随机。

工程上的做法是句柄模式：DLL 内部维护对象，对外只暴露一个不透明指针。

extern "C" { IMAGEPROC_API void* IMAGEPROC_CALL ProcCreateContext(int mode); IMAGEPROC_API int IMAGEPROC_CALL ProcRun(void* ctx, const unsigned char* data, int len); IMAGEPROC_API void IMAGEPROC_CALL ProcDestroyContext(void* ctx); }

C# 侧用IntPtr接这个句柄，用完调ProcDestroyContext销毁。ProcCreateContext和ProcDestroyContext必须成对提供，一个都不能少。我在代码评审时看到只有 Create 没有 Destroy 的接口，基本可以直接打回去重写。

这套模式的好处是：C++ 侧可以自由地用 C++ 的对象、容器、智能指针，只要把裸指针转换成void*交出去就行，内部实现完全不受约束。C# 侧不需要知道里面是什么，只当它是个不透明的编号。职责边界清晰，谁也不用操心对方的内存管理。

3. 动手实现：从零到跑通第一条调用

3.1 C++ 侧的工程配置与导出实现

假设我们做一个模拟项目，功能是图像灰度化加边缘检测，对外提供初始化和处理两个接口。新建一个"动态链接库(DLL)"工程，把上面的头文件加进去，实现文件大概是这样：

// image_proc.cpp #include "image_proc.h" #include <cstring> #include <vector> #include <string> namespace { thread_local std::string g_lastError; void SetError(const char* msg) { g_lastError = msg ? msg : ""; } } extern "C" { int IMAGEPROC_CALL ProcInit(void) { try { // 这里做初始化：预分配缓冲区、加载查找表等 SetError(""); return 0; } catch (...) { SetError("init failed with unknown exception"); return -1; } } int IMAGEPROC_CALL ProcProcess(const unsigned char* src, int width, int height, unsigned char* dst, int* outLen) { if (!src || !dst || !outLen || width <= 0 || height <= 0) { SetError("invalid argument"); return -2; } try { const int pixelCount = width * height; for (int i = 0; i < pixelCount; ++i) { // 简化的灰度化：假设输入是 3 通道 const int off = i * 3; dst[i] = static_cast<unsigned char>( 0.299 * src[off] + 0.587 * src[off + 1] + 0.114 * src[off + 2]); } *outLen = pixelCount; SetError(""); return 0; } catch (const std::exception& e) { SetError(e.what()); return -3; } catch (...) { SetError("process failed with unknown exception"); return -4; } } int IMAGEPROC_CALL ProcGetLastError(char* buf, int bufSize) { if (!buf || bufSize <= 0) return -2; const size_t len = g_lastError.size(); const size_t copyLen = (len < static_cast<size_t>(bufSize - 1)) ? len : bufSize - 1; std::memcpy(buf, g_lastError.c_str(), copyLen); buf[copyLen] = '\0'; return 0; } }

这段代码有几个设计决定需要解释。

每个导出函数都套 try/catch。这不是防御性编程的洁癖，是硬要求。C++ 异常一旦穿过 DLL 边界进入 CLR，行为是未定义的，实际表现就是进程直接终止，C# 侧的try/catch根本接不住。所以异常必须在 DLL 边界内消化掉，转换成错误码返回。catch 的顺序也有讲究：先捕具体的std::exception拿到what()，再捕...兜底，因为不是所有异常都继承自std::exception。

错误信息用thread_local。用全局std::string在多线程场景下会被并发写坏。thread_local保证每个线程有自己的错误槽，配合"先调接口，失败了再取错误信息"的使用模式刚好。注意这是 C++11 起的特性，老编译器要用__declspec(thread)。

参数校验放在 try 外面。空指针、非法尺寸这类问题不需要异常机制，直接返回错误码更快，也避免在 catch 里再出问题。

工程配置上有两个地方要检查：一是"配置类型"必须是 DLL；二是运行库选项。如果你希望这个 DLL 拿到任何机器上都能跑、不需要用户装 VC 运行库，就把"运行库"改成"多线程(/MT)"，把运行库静态链接进去，代价是 DLL 体积大几百 KB。如果目标环境已经统一部署了运行库，用"多线程 DLL(/MD)"更省空间。这个选择在交付前一定要定下来，临时改会很麻烦。

3.2 C# 侧的 P/Invoke 声明

C# 侧把原生方法集中放在一个internal static class里，这是社区里比较通行的组织方式，好处是调用点看到NativeMethods.ProcProcess(...)就知道这是原生调用，不会和普通方法混淆。

using System; using System.Runtime.InteropServices; using System.Text; internal static class NativeMethods { private const string DllName = "imageproc"; [DllImport(DllName, CallingConvention = CallingConvention.StdCall)] public static extern int ProcInit(); [DllImport(DllName, CallingConvention = CallingConvention.StdCall)] public static extern int ProcProcess( byte[] src, int width, int height, byte[] dst, out int outLen); [DllImport(DllName, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)] public static extern int ProcGetLastError(StringBuilder buf, int bufSize); }

DllName这里写的是"imageproc"，不带.dll后缀。Windows 上两种写法都能用，但省略后缀的写法在跨平台项目里更通用（Linux 上是libimageproc.so，封送器会自动补前后缀）。如果你的项目只在 Windows 上跑，写全"imageproc.dll"也没问题。

CallingConvention.StdCall必须和 C++ 侧的__stdcall对上。这是硬性配对，不能靠猜。

调用侧大概长这样：

public static byte[] ToGray(byte[] rgb, int width, int height) { if (NativeMethods.ProcInit() != 0) throw new InvalidOperationException("native init failed"); var gray = new byte[width * height]; int written; int ret = NativeMethods.ProcProcess(rgb, width, height, gray, out written); if (ret != 0) { var sb = new StringBuilder(512); NativeMethods.ProcGetLastError(sb, sb.Capacity); throw new InvalidOperationException($"process failed: {ret}, {sb}"); } if (written != gray.Length) Array.Resize(ref gray, written); return gray; }

这里gray数组必须先按最大可能长度分配好再传进去，因为 C++ 侧不能替你分配内存。这是"调用方提供缓冲区"模式的必然要求。如果你不确定输出多大，就设计成两步：先调一个ProcGetOutputSize拿长度，再分配缓冲区，再调处理函数。多一次调用，换来确定性，值得。

3.3 结构体与数组的封送实战

真实项目里很少只传基本类型，结构体几乎是必用的。假设我们要把处理参数打包成一个结构体传进去：

#pragma pack(push, 4) struct ProcOptions { int mode; // 处理模式 int threshold; // 阈值 float scale; // 缩放系数 bool keepAlpha; // 是否保留透明通道 }; #pragma pack(pop) IMAGEPROC_API int IMAGEPROC_CALL ProcRunWithOptions( void* ctx, const ProcOptions* opt, unsigned char* out, int* outLen);

对应 C# 侧：

[StructLayout(LayoutKind.Sequential, Pack = 4)] public struct ProcOptions { public int Mode; public int Threshold; public float Scale; [MarshalAs(UnmanagedType.I1)] public bool KeepAlpha; } [DllImport("imageproc", CallingConvention = CallingConvention.StdCall)] public static extern int ProcRunWithOptions( IntPtr ctx, ref ProcOptions opt, byte[] output, out int outLen);

三个要点。第一，Pack = 4对应#pragma pack(push, 4)，不写就会按自然对齐补空洞，字段位置全乱。第二，bool必须加I1特性，原因前面说过。第三，ref ProcOptions表示传指针，如果 C++ 侧是const ProcOptions*，用in ProcOptions语义更贴切（C# 7.2 起支持），能避免误改。

如果结构体里含指针或者字符串，麻烦程度会翻倍。比如char name[64]这种定长字符数组，C# 侧要用[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] public string Name;。如果是char*指针，C# 里就得用IntPtr，然后手工Marshal.PtrToStringAnsi转换，并且要判断这个指针指向的内存由谁负责释放。这类结构体我一般能避就避，接口设计时尽量拆成"传字符串 + 传结构体"两个参数，比塞在结构体里干净得多。

数组的封送有个性能细节值得提一句。byte[]作为参数时，封送器默认会把数组 pin 住（blittable 类型直接传指针），没有拷贝开销。但如果你传的是string[]这种非 blittable 类型，封送器会逐元素转换，开销大得多，而且默认只能传输入不能回填。所以数组参数尽量用byte[]、int[]、float[]这类可以直接传指针的类型。

3.4 回调函数的上手与引用保持

进度回调是实际项目里最常见的需求，因为图像处理动辄几秒，界面不能卡死。C++ 侧先定义函数指针类型：

typedef void (IMAGEPROC_CALL *ProgressCallback)(int percent, const char* message); IMAGEPROC_API int IMAGEPROC_CALL ProcRunAsync(void* ctx, ProgressCallback cb);

C# 侧对应：

[UnmanagedFunctionPointer(CallingConvention.StdCall, CharSet = CharSet.Ansi)] public delegate void ProgressCallback(int percent, string message); [DllImport("imageproc", CallingConvention = CallingConvention.StdCall)] public static extern int ProcRunAsync(IntPtr ctx, ProgressCallback cb);

UnmanagedFunctionPointer这个特性是必须的，它告诉封送器"这个委托要被转成原生函数指针，调用约定是什么"。不写的话默认值不一定和 C++ 侧一致，32 位下会出栈问题。

真正的坑在于引用保持。下面这段代码看起来没问题，实际上是定时炸弹：

// 错误示范 public void Run() { NativeMethods.ProcRunAsync(_ctx, (p, m) => UpdateProgress(p, m)); }

匿名委托没有强引用，方法返回后 GC 随时可能把它回收。C++ 那边还在跑，某次回调时就跳到已经被回收的内存上，进程直接消失，什么日志都没有。正确做法是把委托存为字段：

private ProgressCallback _progressCallback; public void Run() { _progressCallback ??= new ProgressCallback(OnProgress); NativeMethods.ProcRunAsync(_ctx, _progressCallback); } private void OnProgress(int percent, string message) { try { UpdateProgress(percent, message); } catch (Exception ex) { Log.Error(ex, "progress callback failed"); } }

??=保证委托只创建一次，字段持有强引用，GC 不会回收它。回调方法内部必须整体 try/catch，因为从托管回调抛出的异常如果穿过原生栈帧，同样会导致进程终止，而且这种终止通常连 Windows 错误报告都不弹。

还有一个场景要注意：如果 C++ 侧是多线程触发回调，C# 的UpdateProgress里更新 UI 必须切回主线程，用Dispatcher.BeginInvoke或者Control.BeginInvoke。直接在回调线程里改控件属性，会抛跨线程访问异常，而且这种异常同样会穿过原生边界，后果一样严重。

3.5 编译、部署与第一次联调

第一次联调建议用一个最小的控制台程序，不要一上来就集成到业务项目里。控制台的干扰因素少，出问题容易定位。

C++ 工程先编译，配置选Release | x64。编译完到输出目录确认.dll和.lib都在（.lib是静态链接用的，纯DllImport场景用不上，但说明导出成功了）。用dumpbin /exports imageproc.dll看一眼导出表，确认函数名干干净净，没有@后缀，没有?开头的修饰名。这一步别省，很多问题在这一步就能发现。

然后在 C# 控制台项目里把平台目标也设成 x64，把 DLL 拷到输出目录，注意是和.exe同目录，不是随便哪个目录。在Program.cs写一个最简单的调用，加try/catch包住，跑起来。

如果第一次就报DllNotFoundException，八成是位数不匹配或者 DLL 根本没拷过去。如果是EntryPointNotFoundException，回去用dumpbin对照导出名。如果进去了但崩了，那就是封送或者内存的问题，用 4.1 节的排查方法定位。

调试配置很简单但很多人不知道：C# 项目属性 → 调试 → 勾选"启用非托管代码调试"。勾上之后，C++ 侧的断点就能命中了，可以像调试普通代码一样单步进入原生函数。这个开关是我带新人时必讲的一条，因为不开的话，你只能对着崩溃地址看汇编码，效率差十倍。

4. 报错现场：常见异常与排查实录

4.1 加载阶段的三类异常

DllNotFoundException: Unable to load DLL 'xxx'。这个异常的含义是 CLR 连文件都没找到，或者找到了但加载失败（依赖缺失也会报这个）。排查顺序：先确认文件在不在预期目录，Path.GetDirectoryName(typeof(Program).Assembly.Location)打一下实际路径；再确认位数，C# 编译成 x64 就要用 x64 编译的 DLL，混用必然失败；最后查依赖，用Dependency Walker或者Process Monitor看加载时缺了哪个 Dll。最常见的依赖缺失是 VC 运行库（vcruntime140.dll、msvcp140.dll），解决办法是在 C++ 项目里改成静态链接/MT，或者把这几个运行时文件一起拷过去。

BadImageFormatException: An attempt was made to load a program with an incorrect format。这个名字有点误导，它跟"镜像格式"其实关系不大，绝大多数情况就是位数不匹配。x64 进程去加载 x86 的 DLL，或者反过来。注意一个坑：如果你在 64 位系统上跑一个 AnyCPU 的 C# 程序，它默认是以 64 位运行的，这时候你拿一个 32 位编译的 DLL 就会报这个错。解决办法是两边统一，或者在 C# 项目里显式锁定平台。

EntryPointNotFoundException: Unable to find an entry point named 'xxx'。文件加载成功了，但导出表里找不到这个名字。原因就那么几个：C++ 侧忘了写extern "C"，导出名被 C++ 修饰成了?ProcInit@@YAHXZ之类；32 位下__stdcall给名字加了_ProcInit@0前后缀；大小写不一致（Windows 的导出表是大小写敏感的，虽然加载器本身不敏感）；或者你调的是 C++ 类成员函数，那玩意根本不会以普通函数形式导出。

判断方法很直接：dumpbin /exports把导出表打出来，一个字一个字对照。我习惯在联调前先把导出表贴进项目文档，谁改坏了马上就能发现。

4.2 调用阶段的崩溃与返回值异常

函数进去了，但结果不对，这类问题比加载失败更难查，因为没有任何异常提示。

栈损坏。典型表现是函数返回后，局部变量莫名其妙变了，或者调用下一条语句时崩在不相干的地方。原因基本只有一个：调用约定不匹配。x86 下__cdecl和__stdcall对"谁清栈"的约定不同，错配就是 ESP 偏移。查法是确认 C++ 头文件里的宏定义和 C# 声明里的CallingConvention严格对应，一个字都不能差。x64 下这个问题基本不存在，因为只有一个约定。

数据错位。传进去的结构体，C++ 侧读出来字段全是乱的值。这是对齐或者类型不匹配。用offsetof和Marshal.OffsetOf对偏移，是定位这类问题最快的手段。另外要检查bool是不是漏了I1特性，long有没有搞混（C++ 的long是 32 位，C# 的long是 64 位），这个错配特别隐蔽，因为在 x64 下 C++ 的long依然是 32 位，但 C# 的long是 64 位，两边一传，后 4 个字节就是垃圾数据。

内存泄漏。跑一段时间内存持续上涨，多半是 Create 和 Destroy 没配对，或者某个返回字符串的接口忘了释放。定位方法是给每个 Create/Delete 加计数日志，跑一天看数字是否平衡。我一般会在 DLL 里加一个ProcGetLiveObjectCount调试接口，联调期打开，上线前关掉，成本很低但很有用。

进程直接消失，没有异常。这是最难受的一种。几种典型成因：C++ 异常穿过了 DLL 边界；托管回调里抛异常穿过了原生栈帧；访问了已经被释放的内存或已被 GC 回收的委托。这三种情况都不会走正常的异常处理流程，直接终止进程。排查手段有限，只能靠代码审查 + 日志。我的做法是在每个导出函数入口和出口各打一条日志（用文件或者OutputDebugString），进程消失时看最后一条日志停在哪，能缩小到一个函数。这个方法笨，但有效。

4.3 问题速查表

5. 工程化细节与个人踩坑体会

5.1 版本、路径与部署

DLL 的加载路径问题在实际部署时特别容易出。默认情况下，Windows 会按一套固定的顺序搜索，当前工作目录排得很靠前。这意味着如果用户从别的目录启动你的程序，工作目录可能不是 exe 所在目录，DLL 就找不到了。稳妥的做法有两种：一是保证 DLL 和 exe 同目录，并且在代码里用绝对路径加载；二是启动时调用SetDllDirectory把 DLL 目录加进搜索路径。

绝对路径加载的写法是[DllImport(@"C:\full\path\imageproc.dll")]，但这样写死了路径，部署时很别扭。我一般用一个静态构造函数加上NativeLibrary.SetDllImportResolver（.NET Core 3.0 起支持），在运行时决定加载哪个路径，兼顾了灵活性和可控性。

版本管理是另一个容易被忽略的点。DLL 一旦发出去，接口就不能随便改了。新增函数没问题，但改函数签名、改结构体字段顺序、改调用约定，都会让老版本调用方直接崩。我的做法是接口里带一个版本号，初始化时校验：ProcInit(int expectVersion)，版本不匹配就返回明确的错误码，而不是让它在后面某个奇怪的地方崩掉。这个成本很低，但能省掉大量现场排查。

命名上也有个小技巧：DLL 文件名带上位数或者架构标识，比如imageproc_x64.dll和imageproc_x86.dll，放在同一个目录下，C# 侧根据IntPtr.Size动态选择。这样同一份安装包可以同时支持 32 位和 64 位客户端，不用出两个版本。

5.2 异常隔离与日志

我在每个项目里都会强调一件事：DLL 边界必须是一道防火墙。所有异常在边界内消化，出去只有错误码。

C++ 侧的实现方式是每个导出函数都套 try/catch，这一点前面已经写过。C# 侧也一样，所有回调方法都要 try/catch，不能让异常往回穿。有人觉得这是过度防御，但你要知道，穿过原生边界的异常不会给你堆栈信息，不会弹错误对话框，就是进程消失。在客户现场出现这种情况，你连从哪查都不知道。

错误码的设计也值得花点心思。简单的 0 成功、非 0 失败够用，但如果错误种类多，最好定义一套枚举，并且让 DLL 提供的ProcGetLastError返回人类可读的描述。这样 C# 侧打日志的时候能直接带上原因，比只看到一个-3强太多。

日志方面，C++ 侧不要用printf或者cout，DLL 没有控制台，输出会丢失。用OutputDebugString配合 DebugView 工具看，或者写文件。生产环境建议把日志级别做成可配置的，默认只记错误，调试时打开详细日志。日志文件路径最好由调用方传进来，而不是 DLL 自己决定写哪，因为 DLL 对文件系统的权限不一定和主程序一致。

5.3 我踩过的几个坑

说几个具体的，都是花了时间才搞明白的。

第一个是char*返回值。早年写了个GetVersion()返回内部静态字符串，C# 侧用string接，一直好好的。后来有人改成多线程调用，偶尔出现版本号变成半截或者乱码。原因是静态缓冲区被并发写坏了。后来改成调用方传缓冲区，问题消失。这个教训让我后来所有字符串接口都走"传 buffer + size"的模式，虽然调用方麻烦一点，但确定性高。

第二个是委托被回收。一个进度回调的项目，测试环境跑了三天没事，现场跑了两周崩了一次。日志里什么都没有，就是进程没了。查了很久才想到是匿名委托没有强引用。改成字段持有之后彻底解决。这个坑我现在写在团队规范第一条：任何传给原生的委托，必须有字段或者 GCHandle 持有引用。

第三个是bool封送。一个配置结构体里有个bool enabled，C# 侧写得好好的，传到 C++ 侧读出来永远是true。原因就是 4 字节封送把后面的字段也吃进去了，读到的值其实是相邻字段的低字节。加上[MarshalAs(UnmanagedType.I1)]就好了。这个错很难从现象反推，因为字段值看起来"有值"，只是值不对。

第四个是静态链接运行库。有个项目交付到客户机器上，DllNotFoundException，查了半天发现客户机器没装 VC 运行库。后来把 C++ 项目改成/MT重新编译，问题解决，代价是 DLL 从 200KB 涨到 1.2MB。我觉得这个代价值得，尤其是交付给非技术用户的产品。

最后一个跟调试有关。有次 C++ 侧断点死活不命中，查了半天发现是 C# 项目没勾"启用非托管代码调试"。这个开关在一个很深的属性页里，不熟悉的话根本想不到。现在我的做法是在项目模板里就把它打开，省得每次都忘。

这套东西跑通之后，其实后面就是重复劳动了：定义接口、写.def、写DllImport、加 try/catch、联调验证。真正需要动脑的地方在前面的设计阶段——想清楚哪些数据要跨边界、内存归谁管、错误怎么传。这几个问题定下来，剩下的都是照着模板填。