简介面向64位Windows平台进行C/C开发、并希望保持与Unix/Linux工具链兼容的开发者这套MinGW64 x86-64 15.2.0工具集提供了较完整的开源编译环境。它集成GCC/G相关组件支持SEH结构化异常处理与UCRT通用运行时并包含面向Visual Studio 2019的RT v13修订适合跨平台项目迁移、本地编译调试及需要较新运行时特性的工程。压缩包共2000个文件、约173.71MB其中967个.h与243个.hpp头文件构成主要接口声明761个.py脚本多用于构建或辅助处理另有txt说明、sh脚本及少量c样例、md文档与前端配置文件目录组织便于按模块检索。已有805人学习或下载说明其在Windows开发环境搭建中有一定参考价值。对于需要离线获取工具链、核对头文件与运行时组成、减少GitHub下载等待的读者可直接获得较完整的开发组件与兼容性支持便于快速投入项目编译和问题排查。1. 一个字母之差win32 线程模型让 std::thread 编译不过某开发者在旧笔记本上装 MinGW64解压、配 Path、写 hello world一路顺畅。第二天他要写个带后台线程的小工具敲完std::thread t(worker);回车编译器甩回一行红字error: thread in namespace std does not name a type。他换了三个版本的包重装了两遍系统变量甚至怀疑自己 C 学错了。真正的原因藏在压缩包名里那三个字母win32。GCC 的线程模型分 win32 与 posix 两套前者直接调 Windows 原生线程 API构建时 libstdc 不定义_GLIBCXX_HAS_GTHREADSstd::thread、std::mutex、std::future整套并发组件就地蒸发。这种环境太常见了一个几百 MB 的 7z 包解压即用没有安装器看着比装一整套包管理器省事可一旦选错组合它不会当场报错而是等到你写第一行多线程代码时才爆。这篇记录的就是mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0这一套从版本拆解、落盘、配 Path 到装坏救回来的全过程给在 Windows 上写 C/C、用 VS Code 或 CMake 的人照着走。2. 拆开文件名再下载15.2.0 的三段关键参数这个文件名六十多个字符每一段都对应编译器的某个开关选错任何一段失败方式都很隐蔽——有时是编译期一句语法级的报错有时是运行期一个弹窗有时是拿到别人机器上才炸。我自己的习惯是先把文件名拆成几段抄在纸上确认要哪个组合再去发布页找对应文件别看到mingw64开头的就往下点。2.1 从文件名读出版本、线程模型、异常模型和 C 运行库片段实际含义选错的后果mingw64目标为 64 位 Windows三元组x86_64-w64-mingw32拿成 32 位包链接 64 位静态库时格式不匹配x86-64目标 CPU 架构同上交叉链接直接失败15.2.0GCC 主版本号决定 C23 特性的覆盖范围版本太老编不了std::expected、std::printrelease发布构建带优化、无调试断言拿成调试构建产物体积大、跑得慢win32线程模型走 Windows 原生线程 APIstd::thread、std::mutex、std::future全部不可用seh异常模型结构化异常处理仅 x86_64 可用退到 sjlj 每次函数调用都有额外开销ucrtC 运行库为 Universal CRT目标机低于 Win10 且没打 UCRT 补丁时起不来rt_v13mingw-w64 运行时版本 13与 GCC 版本绑定不能单独替换rev0同一组合的第 0 次修订修 bug 会出 rev1有新版优先取新版先说win32这一段因为它是最容易吃亏的地方。win32 线程模型意味着 GCC 运行时直接调用CreateThread那一套系统 API好处是不依赖libwinpthread-1.dll发布时少一个外部文件纯计算型代码的调用开销也更贴近系统代价是 libstdc 在构建阶段就把 C 标准库的并发组件关掉了。注意报错形态它给的是编译错误而不是链接错误很多人第一反应是「头文件没包」或者「标准版本没开」于是往-stdc20上折腾其实是包里根本没这个能力。再看seh。这是 Windows 自己的结构化异常处理x86_64 上栈展开效率高C 异常、try/catch、析构函数在异常路径上的行为都正确sjlj 是 setjmp/longjmp 的老方案兼容性广但每次函数调用都要付一点额外代价。64 位包基本都是 seh只有目标环境必须兼容很老的 32 位系统时才考虑 sjlj正常开发不用纠结。最后是ucrt。程序会依赖系统的ucrtbase.dll和一组api-ms-win-crt-*.dllWindows 10 起系统自带所以产物在 Win10/11 上不需要额外分发 CRT。换成msvcrt那一套兼容性一路回溯到很老的系统但 CRT 实现陈旧宽字符、格式化输出、locale 的行为和现代实现有出入写日志、处理中文时容易踩到不一致。选 ucrt 的代价只有一个目标机不能太老。这三段组合起来——win32 seh ucrt——就是「产物干净、跑得快、但并发库缺席」的一套用之前心里得有数。2.2 系统要求和装前环境清单装之前先把机器扫一遍比装完再回滚省事得多。这套包对系统本身要求不高真正的门槛在运行库和路径。项目要求我一般这么配操作系统Windows 10 1809 及以上、Windows 11Win10 22H2 以上UCRT 系统自带老系统补丁Win7/8.1 需先装 Universal CRT 更新装完重启再编译验证磁盘压缩包几百 MB解压后 1 GB 上下留 3 GB 余量构建中间文件还要占目录无中文、无空格、非系统保护目录C:\dev\mingw64权限普通用户可写不放 Program Files避免每次要管理员已有工具链确认没有别的 gcc 抢 Pathwhere.exe gcc只留一行老系统这条别省。低于 Win10 的机器如果没打 UCRT 补丁编译一切正常双击 exe 却弹「缺少 api-ms-win-crt-runtime-l1-1-0.dll」很容易误判成包的问题实际是系统缺运行库。补丁装完要重启重启之后再谈别的。再确认有没有旧工具链。机器上装过 Anaconda、某些 IDE 自带编译器、旧版 MinGW 的Path里往往已经有一份gcc.exe。装新包之前先开一个干净的终端跑一句where.exe gcc输出为空最省心输出多行说明已经有别的 gcc 在 Path 上记下它们的路径后面配 Path 时要么删掉要么把新的排在前面。这一步做过后面九成的「版本对不上」都不会发生。下载完成后先验一遍完整性压缩包几百 MB网络抖一下就可能损坏解压时只报一句笼统的「数据错误」很难判断是包坏了还是 7-Zip 版本太老# 用 SHA256 核对发布页给出的摘要不一致就重下不要试着修复 Get-FileHash .\mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0.7z -Algorithm SHA256Get-FileHash默认就是 SHA256输出里那串十六进制和发布页贴的对比逐字符看别看头尾。哈希不一致没什么可修的重新下一次比在解压报错上猜半小时划算。2.3 和 MSYS2、w64devkit 的取舍同样是在 Windows 上要一个 gcc路径不止一条。MSYS2 带 pacman能装一大堆预编译库生态最完整代价是它会往Path里塞usr\bin那里有自己的 gcc、自己的 make、自己的动态库和这套独立包放在一起就是一场持久战——where gcc出三行、链接时找不到-lstdc、CMake 挑错编译器基本都是这么来的。w64devkit 更小更省事一个压缩包解压完就带 make 和 busybox 风格的工具版本节奏和这套不一样。我自己的取舍是做纯 Windows 原生开发、依赖不多的项目用这套独立包目录干净、可以同时放好几个版本、删掉不留痕迹项目一旦要拉 Qt、OpenSSL、各种预编译二进制再上 MSYS2把两套分开装在不同盘符Path 只留当前要用的那一条。最忌讳的是两套都挂在 Path 上让系统去猜——它猜错了不会告诉你。3. 解压落盘路径、校验与目录结构这套包没有安装器双击一路下一步那套流程不存在它就是个 7z 压缩包。好处是随时能删、随时能换版本坏处是目录结构、Path、make 的名字全得自己定定错了后面每一步都在还债。解压这一步看着最没技术含量实际上决定了后面能不能顺利跑通。3.1 目录规划为什么我一律放 C:\dev\mingw64三条硬性要求路径短、无空格、无中文。空格会让一部分构建脚本的参数解析出错中文在某些代码页下会变成乱码进而导致gcc: error: CreateProcess: No such file or directory——这个报错极其误导你会以为是缺文件其实是路径编码问题。再加一条不要放C:\Program Files下面那里的写权限受限gcc生成临时文件、make写中间产物时会被拦报错信息往往只有一句Permission denied。我用的布局是这样版本号只出现在父目录当前在用的统一叫mingw64切换版本时改 Path 或者改目录名都行C:\dev\ ├─ mingw64\ # 当前在用15.2.0 win32-seh-ucrt ├─ mingw64-15.2.0-posix\ # 备选需要 std::thread 时切过去 └─ src\ # 自己的代码和工具链分开这么分的好处很实在项目里的 CMake 缓存、VS Code 的compilerPath、脚本里写死的路径都可以写死成C:\dev\mingw64换版本时不用改一堆配置文件。备选目录那一份不用天天挂 Path 上需要的时候临时切用完切回来。注意别把代码目录塞进工具链目录里将来删旧版本时容易连带删掉东西。3.2 用 7-Zip 解压并核对关键文件Windows 资源管理器不认.7z得装 7-Zip。解压命令和参数如下# 1. 建父目录已存在就跳过 New-Item -ItemType Directory -Force C:\dev | Out-Null # 2. 解压x 表示按原路径展开-o 指定输出目录-y 表示全部覆盖不询问 C:\Program Files\7-Zip\7z.exe x .\mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0.7z -oC:\dev -y # 3. 确认编译器落在预期位置 Test-Path C:\dev\mingw64\bin\gcc.exe三个参数里最容易写错的是-o它和路径之间不能有空格写成-o C:\dev会被当成两个参数7-Zip 直接把内容解到当前目录事后满硬盘找gcc.exe。x和e的区别也要留意e会把所有文件平铺到一个目录里整个目录结构就毁了必须用x。解压出来的压缩包一般自带一层mingw64目录所以-oC:\dev之后正好得到C:\dev\mingw64。如果多套了一层进目录看一眼再决定要不要挪。接着核对关键文件这套包被清理过或者解压不完整时bin下会缺东西路径作用能不能删bin\gcc.exeC 编译器驱动不能bin\g.exeC 编译器驱动不能bin\gdb.exe调试器不调试可删建议留着bin\mingw32-make.exeGNU Make 的 Windows 命名版不能构建要用bin\libstdc-6.dllC 标准库动态库不能删发布时可静态链接绕开bin\libgcc_s_seh-1.dllGCC 底层运行时SEH 版同上bin\libwinpthread-1.dll线程与同步封装这套是 win32 模型但 gcc 自身工具有依赖别手工清x86_64-w64-mingw32\include系统头文件不能x86_64-w64-mingw32\lib导入库与静态库不能这里有个反复出现的事故有人为了「精简」把bin下的 dll 全删了只留 exe。结果gcc.exe一跑就报找不到libisl或者libmpc之类的库——编译器本身也是动态链接的那些 dll 是它自己的口粮。要瘦身可以删share下的文档、lib\gcc下的多版本目录但bin里的东西一个都别动。3.3 一次性目录清理和 make 改名解压完做两件小事后面省很多麻烦。第一件把mingw32-make.exe复制一份改名成make.exe# 很多 Makefile、构建脚本、老教程里直接写 make多一份副本免得改脚本 Copy-Item C:\dev\mingw64\bin\mingw32-make.exe C:\dev\mingw64\bin\make.exe为什么叫mingw32-make而不是make是历史原因——当年为了不和系统里别的make撞名。但大量现成的 Makefile、build.bat、CI 脚本里写的就是make报make 不是内部或外部命令时新手会以为没装 make。复制一份改名最省事两个名字都能用不占多少空间。第二件留个后悔药。把原始压缩包单独存一份到别的盘或者至少记下版本号和下载来源。将来需要换 posix 版本、换更新的修订号或者同事要一套同样的环境直接复制解压不用重新找发布页。我自己吃过这个亏为了省空间删了包半年后要复现一个老项目的构建环境翻了半天才对上版本号。4. 配置环境变量Path 的三条写法和一个截断坑到这一步编译器已经在硬盘上了但终端还不知道它在哪。配 Path 是整个流程里最容易留下隐患的一步图形界面、setx、PowerShell 三种写法效果不一样其中一种会静默毁掉你的用户变量。4.1 图形界面和 setx 的差别后者会截断先说结论用图形界面或者 PowerShell 的 API别用setx。setx有两个硬伤。一是它写的是用户变量字符数超过 1024 会被直接截断而且不报错你以为写成功了重启终端发现后半截路径全没了。二是很多人图省事这么写# 不建议展开 %PATH% 会把系统 Path 和用户 Path 拼在一起整串塞进用户变量 setx PATH %PATH%;C:\dev\mingw64\bin%PATH%展开时是「系统 Path 用户 Path」的合并结果这条命令把合并后的整串写进了用户变量。后果是系统 Path 被复制了一份进用户变量以后系统层面装了新工具用户变量里那份是旧的删掉某个系统目录时用户变量里还留着Path 就开始玄学——同一个命令在 cmd 里能跑在 VS Code 的终端里找不到。图形界面的路径是Win R输sysdm.cpl→ 高级 → 环境变量 → 在「用户变量」里选中Path→ 编辑 → 新建一行C:\dev\mingw64\bin。注意是新建一行不是在原来的字符串末尾手工拼分号拼错了会形成空路径项某些老程序解析 Path 时会在这里卡住。4.2 PowerShell 写法与当前会话生效想脚本化、或者要装到多台机器上用 PowerShell 调 .NET 的接口它不会截断也不会把系统变量混进来$bin C:\dev\mingw64\bin # 读用户级 Path不是合并后的 $env:Path $old [Environment]::GetEnvironmentVariable(Path, User) if (($old -split ;) -notcontains $bin) { $new if ([string]::IsNullOrWhiteSpace($old)) { $bin } else { $old.TrimEnd(;) ; $bin } [Environment]::SetEnvironmentVariable(Path, $new, User) Write-Host 已追加: $bin } else { Write-Host 已存在跳过 }逐句说清楚。GetEnvironmentVariable(Path,User)的第二个参数指定作用域取的是用户变量本身不是$env:Path那个合并视图这是和%PATH%写法最本质的区别。-split ;拆成数组再判断避免同一个路径被重复追加——重复项多了 Path 会超出长度限制。TrimEnd(;)处理末尾已经有分号的情况否则拼出;;。写回时同样指定User不动系统变量。当前已经打开的终端不会自动刷新要么关掉重开要么临时改会话变量# 只在当前窗口生效关掉就没了适合临时验证 $env:Path C:\dev\mingw64\bin; $env:Path注意这里是把新路径拼在前面而不是后面。顺序在 Path 里是有意义的靠前的先命中。机器上如果还有别的 gcc把C:\dev\mingw64\bin放在最前面等于强制优先用这一套比挨个删旧路径稳妥。验证一下where.exe gcc期望只输出一行C:\dev\mingw64\bin\gcc.exe。输出多行说明还有别的工具链在 Path 上回头按 2.2 记下的路径去清理或者把这一条往上挪。4.3 用 gcc -v 核对三行Path 通了之后别急着写代码先跑一次版本查询输出里三行信息必须和你下载的文件名对得上gcc -v正常情况下能看到类似这样的内容不同修订号细节略有差异Target: x86_64-w64-mingw32 Thread model: win32 gcc version 15.2.0 (GCC)Target对应文件名里的mingw64和x86-64必须是x86_64-w64-mingw32出现i686就是拿错包了。Thread model对应win32这一行是判断能不能用std::thread的唯一依据别靠猜。gcc version对应15.2.0如果显示的是别的版本号说明命中的是另一套工具链回 4.2 查 Path 顺序。再补两条定位用的命令# 三元组和 Target 一致 g -dumpmachine # 该版本实际使用的 C 标准库动态库位置用于确认 bin 目录没被拆散 g -print-file-namelibstdc-6.dll-print-file-name会输出一个绝对路径指向C:\dev\mingw64\bin\libstdc-6.dll。如果它只回显一个文件名说明库没找到通常是被「精简」过。还有个流传很广的误区网上很多讲交叉编译的文章会让你设C_INCLUDE_PATH、LIBRARY_PATH、CPLUS_INCLUDE_PATH。这套包不需要。gcc 会以自身可执行文件的位置为基准去../x86_64-w64-mingw32/include和../x86_64-w64-mingw32/lib找头文件和库。手工设这些变量反而会打乱搜索顺序把系统头文件顶掉症状是编一个#include stdio.h都报找不到——我见过有人为此重装了三遍系统。5. 避坑与排查五条装完才暴露的错装完之后能编译 hello world不等于环境就对了。下面五条都是我自己或者身边的人真实遇到过的按「现象 → 原因 → 解决」记方便对照。5.1 编译期std::thread 那一行红字现象代码里写了std::thread、std::mutex或者std::async编译报thread in namespace std does not name a type或者mutex has not been declared。同一份代码换台机器、换个编译器又能过。原因这套包的线程模型是win32libstdc 在构建时没有开启_GLIBCXX_HAS_GTHREADSC 标准库的并发组件整块不存在。注意它是编译期就失败不是链接期所以看链接命令、看-pthread参数都找不到问题。解决要么换线程模型为posix的同版本包文件名里win32换成posix两个目录并存改 Path 顺序切换要么在代码层面绕开标准库并发组件直接用 Windows 线程 API或者引入项目自带的线程封装库。判断项目要不要 posix 很简单搜一遍源码里有没有std::thread、std::mutex、std::condition_variable、std::future有就得换。纯计算、单线程的命令行工具用 win32 版没问题产物还少一个 dll 依赖。5.2 运行期三个 DLL 和一堆方块现象一自己机器上双击 exe 正常拷到同事机器或者测试服务器上弹窗「无法启动此程序因为计算机中丢失 libstdc-6.dll」。换成libgcc_s_seh-1.dll、libwinpthread-1.dll也是同样的剧本。原因gcc 默认动态链接自己的运行库这几个 dll 躺在C:\dev\mingw64\bin里。你的机器 Path 上有这个目录加载器能找到别人机器上没有就找不着。很多人在开发机上测通了就以为没事交付时才炸。解决编译时显式静态链接 GCC 运行时# 只静态链接 gcc 运行时系统库仍然动态产物增量小兼容性够用 g -stdc20 -O2 main.cpp -o app.exe -static-libgcc -static-libstdc # 全静态连 libwinpthread 之类一起打进去产物最大最省心 g -stdc20 -O2 main.cpp -o app-static.exe -static-static-libgcc和-static-libstdc分别管 GCC 底层运行时和 C 标准库这两个加上之后普通的单文件程序基本不再依赖 MinGW 目录下的任何 dll。-static是更彻底的做法把能静态的都静态掉代价是产物变大、某些依赖动态加载的库比如插件式加载的模块要单独处理。验证方式在下一章。现象二printf(中文)在 cmd 里输出一堆方块或者问号或者源文件里带中文注释编译报stray \357 in program。原因源文件存的是 UTF-8GCC 默认输入字符集和执行字符集都是 UTF-8而 cmd 默认代码页是 936GBK。两边对不上要么是编译期解析注释出错要么是运行期终端把 UTF-8 字节按 GBK 解释。解决两条路选一条统一就行。一是让 exe 输出 GBK编译时加-fexec-charsetGBK终端不用动二是把终端切成 UTF-8chcp 65001然后在 VS Code 的settings.json里把终端编码固定住。我一般选第二条因为跨平台项目里源文件统一 UTF-8 更省事切终端只是本地习惯。5.3 环境层Path 和多工具链打架现象一gcc -v显示的版本不是刚解压的那个或者编译时报fatal error: bits/cconfig.h: No such file or directory——这个头文件明明在包里躺着。原因机器上存在多套工具链Path里靠前的那一套先被命中。头文件找不到是因为 gcc 驱动来自 A 版本而搜索路径按 A 的位置算实际的头文件属于 B 版本两边错位。解决where.exe gcc列出全部命中项逐个确认来源。把不用的从用户 Path 里删掉或者把C:\dev\mingw64\bin上移到最前。改完必须重开终端已经打开的窗口读的是旧环境。清理完再跑一次where.exe gcc只留一行才算干净。现象二Path 莫名其妙少了一截某些系统目录不见了一部分命令在 cmd 里能跑、在 PowerShell 里报找不到。原因之前用setx PATH %PATH%;...写过用户变量被 1024 字符截断或者系统 Path 被复制进了用户变量。解决打开注册表编辑器看HKEY_CURRENT_USER\Environment下Path的原始值把被截断的后半段补回来系统级的看HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment那个不要随便动。补完之后按 4.2 的 PowerShell 写法维护别再碰setx。这类事故恢复起来麻烦最好的办法是改之前先导出一次用户变量做备份。6. 装完怎么验证三分钟跑通一个多文件 C20 demo单文件 hello world 只能证明gcc.exe能跑证明不了头文件路径、库路径、链接器、C 标准库这几件事都对。我一般用一个最小的多文件工程做验收三分钟能跑完出问题也能立刻定位到是哪一层。6.1 命令行三步自检先准备两个源文件和一个头文件故意跨文件调用顺便用一个 C20 特性// mathx.h #pragma once #include vector int sum_even(const std::vectorint v); // 跨文件调用验证头文件和链接// mathx.cpp #include mathx.h int sum_even(const std::vectorint v) { int s 0; for (int x : v) if (x % 2 0) s x; return s; }// main.cpp #include cstdio #include vector #include ranges // C20用来确认标准版本真的开了 #include mathx.h int main() { std::vectorint v{1, 2, 3, 4, 5, 6}; auto even v | std::views::filter([](int x){ return x % 2 0; }); int s 0; for (int x : even) s x; std::printf(sum%d, cross-file%d\n, s, sum_even(v)); return s sum_even(v) ? 0 : 1; }编译并运行然后看依赖# 1) 编译开 C20、 p a hrefhttps://download.csdn.net/download/admans/91941352 stylecolor:#ec7500;font-size:14px; 本文还有配套的精品资源点击获取 /a img altmenu-r.4af5f7ec.gif srchttps://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif stylewidth:16px;margin-left:4px;vertical-align:text-bottom;cursor:text; /p 
长河君 · 2026/10/28 6:06:32 · 阅读 1.2k win32线程模型为何让std::thread编译失败：MinGW64避坑指南
简介面向64位Windows平台进行C/C开发、并希望保持与Unix/Linux工具链兼容的开发者这套MinGW64 x86-64 15.2.0工具集提供了较完整的开源编译环境。它集成GCC/G相关组件支持SEH结构化异常处理与UCRT通用运行时并包含面向Visual Studio 2019的RT v13修订适合跨平台项目迁移、本地编译调试及需要较新运行时特性的工程。压缩包共2000个文件、约173.71MB其中967个.h与243个.hpp头文件构成主要接口声明761个.py脚本多用于构建或辅助处理另有txt说明、sh脚本及少量c样例、md文档与前端配置文件目录组织便于按模块检索。已有805人学习或下载说明其在Windows开发环境搭建中有一定参考价值。对于需要离线获取工具链、核对头文件与运行时组成、减少GitHub下载等待的读者可直接获得较完整的开发组件与兼容性支持便于快速投入项目编译和问题排查。1. 一个字母之差win32 线程模型让 std::thread 编译不过某开发者在旧笔记本上装 MinGW64解压、配 Path、写 hello world一路顺畅。第二天他要写个带后台线程的小工具敲完std::thread t(worker);回车编译器甩回一行红字error: thread in namespace std does not name a type。他换了三个版本的包重装了两遍系统变量甚至怀疑自己 C 学错了。真正的原因藏在压缩包名里那三个字母win32。GCC 的线程模型分 win32 与 posix 两套前者直接调 Windows 原生线程 API构建时 libstdc 不定义_GLIBCXX_HAS_GTHREADSstd::thread、std::mutex、std::future整套并发组件就地蒸发。这种环境太常见了一个几百 MB 的 7z 包解压即用没有安装器看着比装一整套包管理器省事可一旦选错组合它不会当场报错而是等到你写第一行多线程代码时才爆。这篇记录的就是mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0这一套从版本拆解、落盘、配 Path 到装坏救回来的全过程给在 Windows 上写 C/C、用 VS Code 或 CMake 的人照着走。2. 拆开文件名再下载15.2.0 的三段关键参数这个文件名六十多个字符每一段都对应编译器的某个开关选错任何一段失败方式都很隐蔽——有时是编译期一句语法级的报错有时是运行期一个弹窗有时是拿到别人机器上才炸。我自己的习惯是先把文件名拆成几段抄在纸上确认要哪个组合再去发布页找对应文件别看到mingw64开头的就往下点。2.1 从文件名读出版本、线程模型、异常模型和 C 运行库片段实际含义选错的后果mingw64目标为 64 位 Windows三元组x86_64-w64-mingw32拿成 32 位包链接 64 位静态库时格式不匹配x86-64目标 CPU 架构同上交叉链接直接失败15.2.0GCC 主版本号决定 C23 特性的覆盖范围版本太老编不了std::expected、std::printrelease发布构建带优化、无调试断言拿成调试构建产物体积大、跑得慢win32线程模型走 Windows 原生线程 APIstd::thread、std::mutex、std::future全部不可用seh异常模型结构化异常处理仅 x86_64 可用退到 sjlj 每次函数调用都有额外开销ucrtC 运行库为 Universal CRT目标机低于 Win10 且没打 UCRT 补丁时起不来rt_v13mingw-w64 运行时版本 13与 GCC 版本绑定不能单独替换rev0同一组合的第 0 次修订修 bug 会出 rev1有新版优先取新版先说win32这一段因为它是最容易吃亏的地方。win32 线程模型意味着 GCC 运行时直接调用CreateThread那一套系统 API好处是不依赖libwinpthread-1.dll发布时少一个外部文件纯计算型代码的调用开销也更贴近系统代价是 libstdc 在构建阶段就把 C 标准库的并发组件关掉了。注意报错形态它给的是编译错误而不是链接错误很多人第一反应是「头文件没包」或者「标准版本没开」于是往-stdc20上折腾其实是包里根本没这个能力。再看seh。这是 Windows 自己的结构化异常处理x86_64 上栈展开效率高C 异常、try/catch、析构函数在异常路径上的行为都正确sjlj 是 setjmp/longjmp 的老方案兼容性广但每次函数调用都要付一点额外代价。64 位包基本都是 seh只有目标环境必须兼容很老的 32 位系统时才考虑 sjlj正常开发不用纠结。最后是ucrt。程序会依赖系统的ucrtbase.dll和一组api-ms-win-crt-*.dllWindows 10 起系统自带所以产物在 Win10/11 上不需要额外分发 CRT。换成msvcrt那一套兼容性一路回溯到很老的系统但 CRT 实现陈旧宽字符、格式化输出、locale 的行为和现代实现有出入写日志、处理中文时容易踩到不一致。选 ucrt 的代价只有一个目标机不能太老。这三段组合起来——win32 seh ucrt——就是「产物干净、跑得快、但并发库缺席」的一套用之前心里得有数。2.2 系统要求和装前环境清单装之前先把机器扫一遍比装完再回滚省事得多。这套包对系统本身要求不高真正的门槛在运行库和路径。项目要求我一般这么配操作系统Windows 10 1809 及以上、Windows 11Win10 22H2 以上UCRT 系统自带老系统补丁Win7/8.1 需先装 Universal CRT 更新装完重启再编译验证磁盘压缩包几百 MB解压后 1 GB 上下留 3 GB 余量构建中间文件还要占目录无中文、无空格、非系统保护目录C:\dev\mingw64权限普通用户可写不放 Program Files避免每次要管理员已有工具链确认没有别的 gcc 抢 Pathwhere.exe gcc只留一行老系统这条别省。低于 Win10 的机器如果没打 UCRT 补丁编译一切正常双击 exe 却弹「缺少 api-ms-win-crt-runtime-l1-1-0.dll」很容易误判成包的问题实际是系统缺运行库。补丁装完要重启重启之后再谈别的。再确认有没有旧工具链。机器上装过 Anaconda、某些 IDE 自带编译器、旧版 MinGW 的Path里往往已经有一份gcc.exe。装新包之前先开一个干净的终端跑一句where.exe gcc输出为空最省心输出多行说明已经有别的 gcc 在 Path 上记下它们的路径后面配 Path 时要么删掉要么把新的排在前面。这一步做过后面九成的「版本对不上」都不会发生。下载完成后先验一遍完整性压缩包几百 MB网络抖一下就可能损坏解压时只报一句笼统的「数据错误」很难判断是包坏了还是 7-Zip 版本太老# 用 SHA256 核对发布页给出的摘要不一致就重下不要试着修复 Get-FileHash .\mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0.7z -Algorithm SHA256Get-FileHash默认就是 SHA256输出里那串十六进制和发布页贴的对比逐字符看别看头尾。哈希不一致没什么可修的重新下一次比在解压报错上猜半小时划算。2.3 和 MSYS2、w64devkit 的取舍同样是在 Windows 上要一个 gcc路径不止一条。MSYS2 带 pacman能装一大堆预编译库生态最完整代价是它会往Path里塞usr\bin那里有自己的 gcc、自己的 make、自己的动态库和这套独立包放在一起就是一场持久战——where gcc出三行、链接时找不到-lstdc、CMake 挑错编译器基本都是这么来的。w64devkit 更小更省事一个压缩包解压完就带 make 和 busybox 风格的工具版本节奏和这套不一样。我自己的取舍是做纯 Windows 原生开发、依赖不多的项目用这套独立包目录干净、可以同时放好几个版本、删掉不留痕迹项目一旦要拉 Qt、OpenSSL、各种预编译二进制再上 MSYS2把两套分开装在不同盘符Path 只留当前要用的那一条。最忌讳的是两套都挂在 Path 上让系统去猜——它猜错了不会告诉你。3. 解压落盘路径、校验与目录结构这套包没有安装器双击一路下一步那套流程不存在它就是个 7z 压缩包。好处是随时能删、随时能换版本坏处是目录结构、Path、make 的名字全得自己定定错了后面每一步都在还债。解压这一步看着最没技术含量实际上决定了后面能不能顺利跑通。3.1 目录规划为什么我一律放 C:\dev\mingw64三条硬性要求路径短、无空格、无中文。空格会让一部分构建脚本的参数解析出错中文在某些代码页下会变成乱码进而导致gcc: error: CreateProcess: No such file or directory——这个报错极其误导你会以为是缺文件其实是路径编码问题。再加一条不要放C:\Program Files下面那里的写权限受限gcc生成临时文件、make写中间产物时会被拦报错信息往往只有一句Permission denied。我用的布局是这样版本号只出现在父目录当前在用的统一叫mingw64切换版本时改 Path 或者改目录名都行C:\dev\ ├─ mingw64\ # 当前在用15.2.0 win32-seh-ucrt ├─ mingw64-15.2.0-posix\ # 备选需要 std::thread 时切过去 └─ src\ # 自己的代码和工具链分开这么分的好处很实在项目里的 CMake 缓存、VS Code 的compilerPath、脚本里写死的路径都可以写死成C:\dev\mingw64换版本时不用改一堆配置文件。备选目录那一份不用天天挂 Path 上需要的时候临时切用完切回来。注意别把代码目录塞进工具链目录里将来删旧版本时容易连带删掉东西。3.2 用 7-Zip 解压并核对关键文件Windows 资源管理器不认.7z得装 7-Zip。解压命令和参数如下# 1. 建父目录已存在就跳过 New-Item -ItemType Directory -Force C:\dev | Out-Null # 2. 解压x 表示按原路径展开-o 指定输出目录-y 表示全部覆盖不询问 C:\Program Files\7-Zip\7z.exe x .\mingw64-x86-64-15.2.0-release-win32-seh-ucrt-rt-v13-rev0.7z -oC:\dev -y # 3. 确认编译器落在预期位置 Test-Path C:\dev\mingw64\bin\gcc.exe三个参数里最容易写错的是-o它和路径之间不能有空格写成-o C:\dev会被当成两个参数7-Zip 直接把内容解到当前目录事后满硬盘找gcc.exe。x和e的区别也要留意e会把所有文件平铺到一个目录里整个目录结构就毁了必须用x。解压出来的压缩包一般自带一层mingw64目录所以-oC:\dev之后正好得到C:\dev\mingw64。如果多套了一层进目录看一眼再决定要不要挪。接着核对关键文件这套包被清理过或者解压不完整时bin下会缺东西路径作用能不能删bin\gcc.exeC 编译器驱动不能bin\g.exeC 编译器驱动不能bin\gdb.exe调试器不调试可删建议留着bin\mingw32-make.exeGNU Make 的 Windows 命名版不能构建要用bin\libstdc-6.dllC 标准库动态库不能删发布时可静态链接绕开bin\libgcc_s_seh-1.dllGCC 底层运行时SEH 版同上bin\libwinpthread-1.dll线程与同步封装这套是 win32 模型但 gcc 自身工具有依赖别手工清x86_64-w64-mingw32\include系统头文件不能x86_64-w64-mingw32\lib导入库与静态库不能这里有个反复出现的事故有人为了「精简」把bin下的 dll 全删了只留 exe。结果gcc.exe一跑就报找不到libisl或者libmpc之类的库——编译器本身也是动态链接的那些 dll 是它自己的口粮。要瘦身可以删share下的文档、lib\gcc下的多版本目录但bin里的东西一个都别动。3.3 一次性目录清理和 make 改名解压完做两件小事后面省很多麻烦。第一件把mingw32-make.exe复制一份改名成make.exe# 很多 Makefile、构建脚本、老教程里直接写 make多一份副本免得改脚本 Copy-Item C:\dev\mingw64\bin\mingw32-make.exe C:\dev\mingw64\bin\make.exe为什么叫mingw32-make而不是make是历史原因——当年为了不和系统里别的make撞名。但大量现成的 Makefile、build.bat、CI 脚本里写的就是make报make 不是内部或外部命令时新手会以为没装 make。复制一份改名最省事两个名字都能用不占多少空间。第二件留个后悔药。把原始压缩包单独存一份到别的盘或者至少记下版本号和下载来源。将来需要换 posix 版本、换更新的修订号或者同事要一套同样的环境直接复制解压不用重新找发布页。我自己吃过这个亏为了省空间删了包半年后要复现一个老项目的构建环境翻了半天才对上版本号。4. 配置环境变量Path 的三条写法和一个截断坑到这一步编译器已经在硬盘上了但终端还不知道它在哪。配 Path 是整个流程里最容易留下隐患的一步图形界面、setx、PowerShell 三种写法效果不一样其中一种会静默毁掉你的用户变量。4.1 图形界面和 setx 的差别后者会截断先说结论用图形界面或者 PowerShell 的 API别用setx。setx有两个硬伤。一是它写的是用户变量字符数超过 1024 会被直接截断而且不报错你以为写成功了重启终端发现后半截路径全没了。二是很多人图省事这么写# 不建议展开 %PATH% 会把系统 Path 和用户 Path 拼在一起整串塞进用户变量 setx PATH %PATH%;C:\dev\mingw64\bin%PATH%展开时是「系统 Path 用户 Path」的合并结果这条命令把合并后的整串写进了用户变量。后果是系统 Path 被复制了一份进用户变量以后系统层面装了新工具用户变量里那份是旧的删掉某个系统目录时用户变量里还留着Path 就开始玄学——同一个命令在 cmd 里能跑在 VS Code 的终端里找不到。图形界面的路径是Win R输sysdm.cpl→ 高级 → 环境变量 → 在「用户变量」里选中Path→ 编辑 → 新建一行C:\dev\mingw64\bin。注意是新建一行不是在原来的字符串末尾手工拼分号拼错了会形成空路径项某些老程序解析 Path 时会在这里卡住。4.2 PowerShell 写法与当前会话生效想脚本化、或者要装到多台机器上用 PowerShell 调 .NET 的接口它不会截断也不会把系统变量混进来$bin C:\dev\mingw64\bin # 读用户级 Path不是合并后的 $env:Path $old [Environment]::GetEnvironmentVariable(Path, User) if (($old -split ;) -notcontains $bin) { $new if ([string]::IsNullOrWhiteSpace($old)) { $bin } else { $old.TrimEnd(;) ; $bin } [Environment]::SetEnvironmentVariable(Path, $new, User) Write-Host 已追加: $bin } else { Write-Host 已存在跳过 }逐句说清楚。GetEnvironmentVariable(Path,User)的第二个参数指定作用域取的是用户变量本身不是$env:Path那个合并视图这是和%PATH%写法最本质的区别。-split ;拆成数组再判断避免同一个路径被重复追加——重复项多了 Path 会超出长度限制。TrimEnd(;)处理末尾已经有分号的情况否则拼出;;。写回时同样指定User不动系统变量。当前已经打开的终端不会自动刷新要么关掉重开要么临时改会话变量# 只在当前窗口生效关掉就没了适合临时验证 $env:Path C:\dev\mingw64\bin; $env:Path注意这里是把新路径拼在前面而不是后面。顺序在 Path 里是有意义的靠前的先命中。机器上如果还有别的 gcc把C:\dev\mingw64\bin放在最前面等于强制优先用这一套比挨个删旧路径稳妥。验证一下where.exe gcc期望只输出一行C:\dev\mingw64\bin\gcc.exe。输出多行说明还有别的工具链在 Path 上回头按 2.2 记下的路径去清理或者把这一条往上挪。4.3 用 gcc -v 核对三行Path 通了之后别急着写代码先跑一次版本查询输出里三行信息必须和你下载的文件名对得上gcc -v正常情况下能看到类似这样的内容不同修订号细节略有差异Target: x86_64-w64-mingw32 Thread model: win32 gcc version 15.2.0 (GCC)Target对应文件名里的mingw64和x86-64必须是x86_64-w64-mingw32出现i686就是拿错包了。Thread model对应win32这一行是判断能不能用std::thread的唯一依据别靠猜。gcc version对应15.2.0如果显示的是别的版本号说明命中的是另一套工具链回 4.2 查 Path 顺序。再补两条定位用的命令# 三元组和 Target 一致 g -dumpmachine # 该版本实际使用的 C 标准库动态库位置用于确认 bin 目录没被拆散 g -print-file-namelibstdc-6.dll-print-file-name会输出一个绝对路径指向C:\dev\mingw64\bin\libstdc-6.dll。如果它只回显一个文件名说明库没找到通常是被「精简」过。还有个流传很广的误区网上很多讲交叉编译的文章会让你设C_INCLUDE_PATH、LIBRARY_PATH、CPLUS_INCLUDE_PATH。这套包不需要。gcc 会以自身可执行文件的位置为基准去../x86_64-w64-mingw32/include和../x86_64-w64-mingw32/lib找头文件和库。手工设这些变量反而会打乱搜索顺序把系统头文件顶掉症状是编一个#include stdio.h都报找不到——我见过有人为此重装了三遍系统。5. 避坑与排查五条装完才暴露的错装完之后能编译 hello world不等于环境就对了。下面五条都是我自己或者身边的人真实遇到过的按「现象 → 原因 → 解决」记方便对照。5.1 编译期std::thread 那一行红字现象代码里写了std::thread、std::mutex或者std::async编译报thread in namespace std does not name a type或者mutex has not been declared。同一份代码换台机器、换个编译器又能过。原因这套包的线程模型是win32libstdc 在构建时没有开启_GLIBCXX_HAS_GTHREADSC 标准库的并发组件整块不存在。注意它是编译期就失败不是链接期所以看链接命令、看-pthread参数都找不到问题。解决要么换线程模型为posix的同版本包文件名里win32换成posix两个目录并存改 Path 顺序切换要么在代码层面绕开标准库并发组件直接用 Windows 线程 API或者引入项目自带的线程封装库。判断项目要不要 posix 很简单搜一遍源码里有没有std::thread、std::mutex、std::condition_variable、std::future有就得换。纯计算、单线程的命令行工具用 win32 版没问题产物还少一个 dll 依赖。5.2 运行期三个 DLL 和一堆方块现象一自己机器上双击 exe 正常拷到同事机器或者测试服务器上弹窗「无法启动此程序因为计算机中丢失 libstdc-6.dll」。换成libgcc_s_seh-1.dll、libwinpthread-1.dll也是同样的剧本。原因gcc 默认动态链接自己的运行库这几个 dll 躺在C:\dev\mingw64\bin里。你的机器 Path 上有这个目录加载器能找到别人机器上没有就找不着。很多人在开发机上测通了就以为没事交付时才炸。解决编译时显式静态链接 GCC 运行时# 只静态链接 gcc 运行时系统库仍然动态产物增量小兼容性够用 g -stdc20 -O2 main.cpp -o app.exe -static-libgcc -static-libstdc # 全静态连 libwinpthread 之类一起打进去产物最大最省心 g -stdc20 -O2 main.cpp -o app-static.exe -static-static-libgcc和-static-libstdc分别管 GCC 底层运行时和 C 标准库这两个加上之后普通的单文件程序基本不再依赖 MinGW 目录下的任何 dll。-static是更彻底的做法把能静态的都静态掉代价是产物变大、某些依赖动态加载的库比如插件式加载的模块要单独处理。验证方式在下一章。现象二printf(中文)在 cmd 里输出一堆方块或者问号或者源文件里带中文注释编译报stray \357 in program。原因源文件存的是 UTF-8GCC 默认输入字符集和执行字符集都是 UTF-8而 cmd 默认代码页是 936GBK。两边对不上要么是编译期解析注释出错要么是运行期终端把 UTF-8 字节按 GBK 解释。解决两条路选一条统一就行。一是让 exe 输出 GBK编译时加-fexec-charsetGBK终端不用动二是把终端切成 UTF-8chcp 65001然后在 VS Code 的settings.json里把终端编码固定住。我一般选第二条因为跨平台项目里源文件统一 UTF-8 更省事切终端只是本地习惯。5.3 环境层Path 和多工具链打架现象一gcc -v显示的版本不是刚解压的那个或者编译时报fatal error: bits/cconfig.h: No such file or directory——这个头文件明明在包里躺着。原因机器上存在多套工具链Path里靠前的那一套先被命中。头文件找不到是因为 gcc 驱动来自 A 版本而搜索路径按 A 的位置算实际的头文件属于 B 版本两边错位。解决where.exe gcc列出全部命中项逐个确认来源。把不用的从用户 Path 里删掉或者把C:\dev\mingw64\bin上移到最前。改完必须重开终端已经打开的窗口读的是旧环境。清理完再跑一次where.exe gcc只留一行才算干净。现象二Path 莫名其妙少了一截某些系统目录不见了一部分命令在 cmd 里能跑、在 PowerShell 里报找不到。原因之前用setx PATH %PATH%;...写过用户变量被 1024 字符截断或者系统 Path 被复制进了用户变量。解决打开注册表编辑器看HKEY_CURRENT_USER\Environment下Path的原始值把被截断的后半段补回来系统级的看HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment那个不要随便动。补完之后按 4.2 的 PowerShell 写法维护别再碰setx。这类事故恢复起来麻烦最好的办法是改之前先导出一次用户变量做备份。6. 装完怎么验证三分钟跑通一个多文件 C20 demo单文件 hello world 只能证明gcc.exe能跑证明不了头文件路径、库路径、链接器、C 标准库这几件事都对。我一般用一个最小的多文件工程做验收三分钟能跑完出问题也能立刻定位到是哪一层。6.1 命令行三步自检先准备两个源文件和一个头文件故意跨文件调用顺便用一个 C20 特性// mathx.h #pragma once #include vector int sum_even(const std::vectorint v); // 跨文件调用验证头文件和链接// mathx.cpp #include mathx.h int sum_even(const std::vectorint v) { int s 0; for (int x : v) if (x % 2 0) s x; return s; }// main.cpp #include cstdio #include vector #include ranges // C20用来确认标准版本真的开了 #include mathx.h int main() { std::vectorint v{1, 2, 3, 4, 5, 6}; auto even v | std::views::filter([](int x){ return x % 2 0; }); int s 0; for (int x : even) s x; std::printf(sum%d, cross-file%d\n, s, sum_even(v)); return s sum_even(v) ? 0 : 1; }编译并运行然后看依赖# 1) 编译开 C20、 p a hrefhttps://download.csdn.net/download/admans/91941352 stylecolor:#ec7500;font-size:14px; 本文还有配套的精品资源点击获取 /a img altmenu-r.4af5f7ec.gif srchttps://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif stylewidth:16px;margin-left:4px;vertical-align:text-bottom;cursor:text; /p