Qt Creator调试报错0xc0000135：静态库与动态库的陷阱

1. 先看你是不是也遇到了“新项目正常老项目一调试就废”的怪圈1.1 这种报错长什么样说实话Qt Creator 里最磨人的报错不是那种编译错误而是“编译全过了一运行就废”的运行时报错。你项目构建成功一脸轻松地按下调试按钮然后 Qt Creator 要么弹个“The inferior stopped because it received a signal from the Operating System”要么程序启动后瞬间闪退要么在《应用程序输出》里输出一句含糊不清的话就没了下文。更常见的表现是弹窗提示During startup program exited with code 0xc0000135这个代码的意思是程序启动失败因为系统找不到必要的 DLL。或者是The program has unexpectedly finished然后就没了。或者 Qt Creator 的控制台里显示qt.qpa.plugin could not be loaded如果你缺的是 Qt 自己的平台插件。你开始在工程配置里翻来覆去地找项目属性改了又改构建套件Kit换了又换编译器从 MSVC 换到 MinGW还是不对。更让你崩溃的是新建一个空项目直接跑调试一切正常。于是你把矛头指向项目配置怀疑是不是 .pro 里那几行针对第三方库的 LIBS 写错了。但事实往往很骨感项目的编译和链接都过了缺的是程序运行起来那一刻需要的东西。链接成功只代表你告诉系统“我要用这个函数库”真正运行起来时系统要按另一条规则去物理加载那些库文件。这一步没有人替你处理缺一个文件整个程序就启动不起来。1.2 为什么“新建项目正常”反而最误导人遇到这种“老项目报错、新项目没事”的情况第一反应确实是对比两个项目到底哪里不一样。一开始你会怀疑项目配置、编辑器构建设置、某个 .pri 文件写错——但对比来对比去发现核心配置完全一致。问题的关键恰恰在于新建项目什么都没引自然没有额外依赖老项目引用了第三方静态库或动态库运行时的依赖链条变长了某个环节断掉就直接启动崩溃。也就是说新项目正常根本不代表你的环境没问题只是它的依赖列表为空自然没有暴露问题。这也是我特别想强调的一点遇到这类“特定项目才能触发、新项目无法复现”的问题别死磕项目设置先考虑运行环境、动态库路径、依赖传递。线索恰恰藏在“为什么这个项目成功另一个项目成功”的反差里。2. 问题本质lib 只是“路线图”dll 才是“物资仓库”2.1 链接期与运行期的分工一张表说明白很多人对“静态库”和“动态库”的理解是错的这个错还不只是新手的错很多写了好几年代码的开发者也经常搞混。我先理一遍 Windows 下最常见的场景阶段发生时机需要什么缺了会发生什么编译编译 .cpp 为 .obj头文件.h编译报错找不到某函数声明链接链接 .obj 和库文件导入库文件.lib链接报错unresolved external symbol运行/调试启动 .exe动态库文件.dll启动失败、闪退、报 0xc0000135看清楚这三点你就知道标题里那句“你使用静态库 lib 的时候没有放动态库 dll 在旁边”其实是一个很典型的混淆。严格说如果你用的是真正的静态库静态链接库它的代码在链接时已经被整体编译进 exe 了根本不需要在运行目录放任何额外文件放不放 dll 跟它无关。但如果你用的是导入库import library也就是动态库配套的那个 .lib 文件那情况就完全不一样了。你在 .pro 里写的LIBS -L$$PWD/../lib -lmylib这里的mylib.lib只是“动态库的索引”或“路线图”它告诉链接器mylib.dll里有哪些导出函数分别是什么地址、什么调用方式。链接器把路线图比对好觉得所有符号都找到了于是生成 exe。这个阶段它根本不需要看到 dll 文件。到了你按 F5 调试那一刻Windows 加载 exe 时发现有mylib.dll的导入表记录于是按顺序去搜索这个 dll 的实际文件。搜索不到程序直接拒绝启动。所以标题那句话如果改得更严谨一点应该是你在链接时引用了动态库的 .lib 导入库编译链接自然通过但程序运行时还需要同名的 .dll 动态库如果它不在加载搜索路径里就会一调试就报错。2.2 Windows 如何在运行/调试时寻找 dllWindows 对 dll 的搜素顺序是有一套规则的从早年的“当前目录优先”到后来微软加了安全限制现在的顺序大致是应用程序所在目录也就是 exe 所在的目录通常是你的构建目录。系统目录C:\Windows\System32。整个 Windows 目录。当前工作目录注意这个位置排序有变化不要依赖它。PATH 环境变量里列出的目录。在 Qt Creator 里调试时它启动程序的方式跟双击 exe 并不完全一致。你双击 exe 时当前目录通常是 exe 所在目录但 Qt Creator 启动调试进程时默认的工作目录可能在项目根目录或者在构建目录之外。这就导致一个现象你在 Qt Creator 里按调试按钮报错但跑到构建目录里手动双击 exe 反而能跑起来。如果你遇到了这种“Qt Creator 里不行、文件夹里直接双击可以”的怪事基本可以判断就是工作目录和动态库搜索路径不一致。更麻烦的是Qt 自带的一些模块比如 platform 插件 qwindows.dll也是动态加载的Qt Creator 调试时会用QT_PLUGIN_PATH等环境变量去找插件。如果你的项目同时依赖第三方 dll 和 Qt 插件报错信息可能五花八门但源头都指向同一个字路径。2.3 一个反直觉的常见误解静态库和导入库的混淆我见过很多人在 .pro 里写CONFIG static LIBS -L$$PWD/../lib -lmylib然后以为这是“静态链接”于是装完动态库也不拷贝 dll最后程序一跑就崩。这里CONFIG static很多时候只影响 Qt 库本身的链接方式第三方库怎么链取决于你给它的是静态库还是导入库。在 Windows 上第三方库发布时通常给你这么一堆文件include/头文件lib/xxx.lib这是导入库不是静态库bin/xxx.dll判断 .lib 是静态库还是导入库可以用文本编辑器打开看或者用 dumpbin 工具看dumpbin /headers xxx.lib | findstr Import如果是导入库文件头里会标注有 Import 相关的描述静态库则是一堆 obj 的打包集合。很多库的官方包同时提供“静态库版本”和“动态库版本”的 .lib名字可能都是xxx.lib不看文档根本分辨不出来。如果你的库是动态库版本那么链接成功后必带运行依赖 dll这是铁律不是配置问题。所以下次再遇到“一调试就报错”先做一件事去查这个项目到底链接了哪些第三方库其中哪些库的安装包里同时带了 bin 目录的 dll。大概率答案就在里面。3. 排查链路一步步确认到底缺了哪个 dll3.1 先从 Qt Creator 的“应用程序输出”和“调试器输出”读取信号排查的第一步永远是把 Qt Creator 底部的“应用程序输出”和“调试器输出”两个窗口打开看完整日志不是看弹窗提示。典型的缺失 dll 报错大致长这样During startup program exited with code 0xc0000135这个错误码我在前面提过本质上就是STATUS_DLL_NOT_FOUND。如果你在 Windows 事件查看器里能看到对应的进程加载失败记录里面甚至不会告诉你缺的是哪个 dll只说加载失败。这是因为 0xc0000135 的异常机制比较老不会自动带上模块名。这时要看 Qt Creator 的完整日志。如果 Qt Creator 的调试器输出了类似Starting debugger... Debugging starts The program has unexpectedly finished.那就说明程序根本没有进入你的 main 函数是在启动早期的加载阶段就失败了。此时别去打断点断点根本不会命中。在 main 函数的第一行设断点也没用因为失败发生在 CRT 初始化之前、入口点执行之前。如果日志里出现了具体的模块名比如C:\xxx\build-xxx\debug\main.exe returns: 0xc0000135那范围就缩小到构建目录下的 exe 和它的直接/间接依赖链。3.2 用依赖检查工具确认缺失项靠肉眼猜哪个 dll 缺了是不现实的直接上工具。旧时代的 Dependency Walker 已经年久失修对现代编译器尤其是 MSVC 生成的程序经常误报一大堆缺失的系统 dll看得人心烦。我的做法是两步走。第一步用微软自家的工具dumpbin需要打开“开发者命令提示符”dumpbin /dependents path\to\your.exe这个命令会把 exe 导入表里列出的所有 dll 按行列出来你能看到类似KERNEL32.dll MSVCP140D.dll mylib.dll Qt5Cored.dll看到mylib.dll出现在列表里而构建目录里没有它那基本就实锤了。第二步用 Process Explorer微软 Sysinternals 工具在程序崩溃瞬间查看加载失败的模块或者在程序能启动、但某些功能不正常时确认是否加载到了旧版本 dll。Process Explorer 能列出进程实际加载的 dll 完整路径配合Find功能搜索某个 dll 名称能很快定位到程序到底从哪个目录加载了这个 dll是不是加载到了和预期版本不一样的旧文件。如果你的程序能启动、但调用某个库函数时崩溃或报错那就不是“找不到 dll”的问题而是“加载了错误版本的 dll”——这个问题比缺文件更隐蔽后面我会专门讲。另外Qt 自带的windeployqt工具干完活之后你也可以直接看构建目录里部署了哪些 Qt 相关 dll这和 dumpbin 的导出列表互相印证就能把手动遗漏的第三方库也找出来。3.3 用系统命令也可以验证修好前的最后一击如果你是在命令行环境里还有一种更高效率的验证方式。先把目标 exe 的目录切到构建目录然后执行cd path\to\build-debug set PATH%PATH%;path\to\thirdparty\bin 你的exe.exe --version如果加了第三方库的 bin 目录到 PATH 之后程序能正常启动那就是缺 dll 实锤。如果加了 PATH 之后还是启动失败再把 Qt 的 bin 目录也加进去试set PATH%PATH%;C:\Qt\5.15.2\msvc2019_64\bin这样一步步扩大搜索范围用二分法排除通常几分钟内就能定位是“第三方库缺失”还是“Qt 模块缺失”。还有一个很多人不知道的命令行小技巧用 PowerShell 检查依赖是否齐全可以把 exe 拖进where.exe的同目录逻辑也可以直接用Test-Path检查关键 dll 是否存在配合 dumpbin 的导入表写个几行的循环脚本就能批量检查一批 exe$exe path\to\your.exe $deps C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.xx\bin\Hostx64\x64\dumpbin.exe /dependents $exe | Select-String \.dll foreach ($d in $deps) { $name ($d -split \s)[1] if (-not (Test-Path .\$name)) { Write-Host MISSING: $name -ForegroundColor Red } }这个思路的核心是用工具把导入表变成清单再用脚本核对清单里的每个项是否出现在构建目录。这比依赖可视化工具更可控。3.4 一个典型的 debug 与 release 差异案例我遇到过一位开发者他的场景跟标题几乎一模一样调试版本Debug一启动就报 0xc0000135但 Release 构建却正常。这就很反直觉因为一般来说 Debug 依赖更多调试库文件Release 反而更干净。排查发现他的项目链接了一个第三方图像处理库库的安装目录里提供了lib\debug\xxx.lib和lib\release\xxx.lib两套导入库但 dll 只有一套在bin\xxx.dll。他的 .pro 里用CONFIG(debug, debug|release)选择了 debug 版本的导入库链接通过了但他忘了把bin\xxx.dll拷贝到 Debug 构建目录。Release 构建用的导入库对应同一套 dll——更诡异的是Release 能跑起来是因为他之前手动往 Release 目录里拷过这个 dllDebug 目录从来没拷过。更常见的 Debug/Release 差异是库官方把 Debug 版 dll 命名为xxxd.dllRelease 版命名为xxx.dll。你的 .pro 里 debug 链接的是xxxd.lib那就必须把xxxd.dll放在运行目录不能拿xxx.dll顶替。因为 Windows 加载器只按导入表里的确切文件名去找不会因为xxxd.dll找不到就自动退回去加载xxx.dll。别觉得“名字少个 d应该兼容吧”——不兼容一个字符都不行。这个案例给我一个非常深刻的教训排查运行时报错一定要把 Debug 和 Release 当成两个完全不同的运行环境来看即使它们用同一套源码依赖路径也是天然隔离的。4. 解决手段三种手动拷贝、加 PATH、用 windeployqt4.1 手动拷贝最快但要注意放对构建目录确认缺了哪个 dll 之后最快的解决方式就是把它拷过去。注意不是拷到项目源码目录而是拷到 Qt Creator 实际生成 exe 的构建目录。很多人容易搞混“项目目录”和“构建目录”。Qt Creator 的“影子构建”默认会把构建产物放在项目旁的 build-xxx-Desktop_Qt_x_x_x_xxx 目录而不是源码目录。判断方式很简单打开 Qt Creator 左侧“项目”面板里面写着“构建目录”值形如C:\Users\xxx\build-project-Desktop_Qt_5_15_2_MSVC2019_64bit-Debug。把 dll 拷贝到这个目录再按 F5大部分情况直接就通了。拷贝时还要注意一点如果程序依赖的第三方库非常多不建议一次拷全部。我习惯的做法是先用 dumpbin 列出 exe 的直接依赖。拷贝缺失的那几个到构建目录。运行程序如果还有报错再重复一次 dumpbin 检查。因为 dll 之间也可能互相依赖A.dll 依赖 B.dll你拷了 A 进去程序启动时又找 B这时报错信息可能还是 0xc0000135但你已经朝正确方向进了一步。逐层推进比一次满天乱猜高效得多。4.2 PATH 环境变量能用但不推荐作为长期方案有人嫌每次都拷贝麻烦直接把第三方库的 bin 目录加进系统 PATH。这个方法见效快但我不推荐作为长期方案原因有三。第一PATH 里的条目是全系统全局生效的所有进程都会去搜索一遍。第三方库的 bin 目录如果还有别的冲突版本 dll这种情况在机器上装了多个 CAD、图像处理、加密库的环境里非常常见可能导致已经正常运行的旧项目突然崩掉。第二Qt Creator 启动调试器时会继承 Qt Creator 进程的环境变量但不一定会实时反射你新加的 PATH。改完 PATH 之后往往要把 Qt Creator 完全关掉重新打开环境变量才生效。第三PATH 方案无法解决“发布给别人用”的问题。你开发阶段靠 PATH 跑通了生成发布包时如果忘了把 dll 带上用户在别的机器上依然报 0xc0000135。相信我发布之后被客户反馈“装了打不开”比开发时自己崩十次还痛苦。所以PATH 只能作为临时应急手段最终都要回归到“把依赖放在 exe 旁边”这个最朴素也最稳的方案。4.3 windeployqtQt 官方部署工具的正确打开方式如果你的项目依赖主要是 Qt 自带的模块并且构建目录里已经拷贝好了第三方库那么部署环节建议直接用 Qt 自带的windeployqt。它会把 Qt 相关的运行库、平台插件、样式插件、翻译文件等一套东西自动部署到 exe 所在目录。用法很简单cd path\to\build-debug C:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe your.exe运行完之后构建目录里会多出一大堆 Qt5*.dll、platforms 目录里面是 qwindows.dll等。这时再按调试Qt 相关报错基本不会再出现。但有两个坑windeployqt 只处理 Qt 自身的依赖不处理你引用的第三方库。所以顺序应该是先用 dumpbin 找出第三方库缺失项并手动拷贝再运行 windeployqt 补 Qt 模块最后再整体验证一次。如果同时装了 Qt 5 和 Qt 6或者 MSVC 版和 MinGW 版不是同一套windeployqt 版本要是选错了部署出来的 dll 和编译器不匹配反而会引入新的运行时错误。务必使用当前构建套件对应的 Qt bin 目录里的 windeployqt。对应标题的场景“你使用静态库 lib 的时候没有放动态库 dll 在旁边”修复手段其实就是把第三方库的 dll 也放到 exe 旁边。windeployqt 管的是 Qt 部分第三方部分还得自己动手两者不冲突。5. 把事情固化进工程在 .pro 里把依赖处理好5.1 QMAKE_POST_LINK 自动拷贝依赖手动拷贝 dll 只是临时解决了问题但如果过几天清空构建目录重新构建你大概率又会忘记拷贝——因为构建过程并不会自动执行“把 dll 复制过去”这件事。所以要让工程自己学会这件事。在 Qt 的 qmake 体系里最顺手的做法是用QMAKE_POST_LINK它在链接完成之后自动执行你指定的命令。比如win32 { CONFIG(debug, debug|release) { DLL_SRC $$PWD/../thirdparty/bin/mylibd.dll DLL_DST $$OUT_PWD/debug } else { DLL_SRC $$PWD/../thirdparty/bin/mylib.dll DLL_DST $$OUT_PWD/release } exists($$DLL_SRC) { QMAKE_POST_LINK $$quote(cmd /c copy /Y \$$DLL_SRC\ \$$DLL_DST\) } }我这里用$$OUT_PWD指代当前构建输出目录避免了硬编码构建路径。调试版和发布版分别对应不同的 dll 文件名带不带 d 后缀这个逻辑要写清楚。因为如果你 debug 构建却去拷贝 release 版的 dll程序可能表面能跑但里面用的库不带调试符号断点进不去变量看不到调试体验直接折损。注意在 qmake 里写QMAKE_POST_LINK的时候路径中有空格需要转义这经常踩坑。上面的示例用$$quote(...)把整条命令包起来并在需要的地方用\转义是经过实测的写法。用 CMake 的话则可以用add_custom_command(TARGET xxx POST_BUILD ...)实现同样的效果。5.2 尽量让第三方库和 Qt 库放同一套目录策略项目的整洁度决定了问题排查的难易度。我经手过很多工程第三方库散落在 C 盘各处各种 dll 混在 PATH 里构建目录里什么都有谁都不是很确定哪些该依赖哪些是冗余。这种工程出现运行时崩溃排查成本极高。这里分享一个自己一直在用的目录约定project_root/ ├── src/ # 项目源码 ├── thirdparty/ # 第三方库统一目录 │ ├── include/ # 头文件 │ ├── lib/ # 导入库.lib分 debug/release │ └── bin/ # 动态库.dll ├── build/ # 构建输出影子构建目录 └── output/ # 发布包收拢目录为了统一路径管理在项目的 .pri 文件里可以定义一组变量THIRDPARTY_ROOT $$PWD/thirdparty THIRDPARTY_INCLUDE $$THIRDPARTY_ROOT/include THIRDPARTY_LIB $$THIRDPARTY_ROOT/lib/$$COMPILER_TYPE THIRDPARTY_BIN $$THIRDPARTY_ROOT/bin然后在链接 LIBS 和部署 DLL 时都引用这组变量避免在源码里到处硬编码绝对路径。这样不管项目换到哪台电脑只要目录结构保持住构建和部署的流程都能平滑迁移。和“把 dll 放 exe 旁边”这个原则结合就变成开发阶段用第三方的 bin 目录配合拷贝脚本进构建目录发布阶段把所需 dll 从第三方 bin 目录统一拷贝进 output 目录。两条路径互不干扰又都有明确的来源。这样做还有个附带好处当项目里同时引用了 Qt 和十几个第三方库时目录一旦失控你甚至不知道程序到底加载的是哪个版本的库排查起来等于从零开始。5.3 剩下的边界坑调试和发布目录不一致、库的位数不匹配最后说说我在实际项目中遇到的几个边界情况尤其是标题里那种“静态库 动态库没有放旁边”的变种都有值得注意的地方。第一构建目录与输出目录不一致。很多人用影子构建构建目录在 build-xxx 下发布目录在 output 下但调试时 Qt Creator 用的是构建目录。你往 output 里拷了 dll构建目录里却没有调试依然报错。所以调试阶段拷贝 dll 的目标必须是 Qt Creator 实际使用的构建目录而不是你发布用的目录。这也是“我明明放了 dll 为什么还报错”的高频原因。第二库位数不匹配。如果你的构建套件是 64 位 MSVC那你的第三方库也必须是 64 位版本。32 位库的 .lib 在链接阶段可能会报错也可能因为符号差异被识别成 unsupported但如果你是用了错误位数的 dll比如 32 位 dll 放在 64 位 exe 旁边启动时会报“不适用于该程序的映像”错误码是 0xc0000005 或加载失败。排查时注意看 dll 的位数用dumpbin /headers xxx.dll | findstr machine能直接查看。第三Qt 和第三方库互相依赖的场景。有些库内部依赖 Qt 的某些模块比如库本身用了 Qt Network 或 Qt GUI。这种情况下库的 dll 加载时需要 Qt 相关 dll 也能被找到拷贝顺序出错会导致库已经加载但 Qt 加载失败。先部署 Qt 相关 dll再放第三方库 dll顺序更合理。第四绝对路径问题被忽略。链接时LIBS -L绝对路径没问题但运行时系统不会按链接路径去寻找 dll。链接器的库搜索路径和 Windows 加载器的 dll 搜索路径是两套完全独立的逻辑。所以哪怕你在 .pro 里清清楚楚写了库的绝对路径运行时不拷贝 dll 照样报错。认识到这一点是修好这一类问题的关键。我个人在实际项目中的处理习惯是写完一个项目之后把“第三方 dll 从何处来、去往何处”写成一个明确的分发清单放在项目根目录的 DEPLOY.md 里。谁接手这个项目、或者三个月后的自己回来维护照着清单就能把运行时依赖处理干净不用再重新把坑踩一遍。然后在一个项目里把这个机制用 QMAKE_POST_LINK 固化下来以后每次构建完构建目录里依赖自动齐整不需要人工干预这个“一调试就报错”的怪圈才算真正告别。