1. 为什么每个Qt程序都该尽早搞定EXE和图标做Qt开发的日子久了你会发现一个挺有意思的现象不管你是写了个几十行的小工具还是憋了大半年的商业项目只要走到“把程序交给别人用”这一步就绕不开两件事——怎么把它变成能双击运行的EXE以及怎么让这个EXE看起来不像个临时货。先说EXE。Qt程序本质上是个二进制可执行文件但跟普通的C程序不太一样它重度依赖Qt运行时库。你在开发环境里点运行按钮很爽因为环境变量、插件路径全都替你配好了可一旦把那个debug版的exe拷到一台新电脑上十有八九会弹窗告诉你“缺少Qt6Core.dll”。所以“生成EXE”这个需求背后真正的核心其实是“生成一套可以在目标机器上独立运行的发布包”这才是大家真正想问的东西。再说图标。Windows用户对图标是很敏感的一个没有图标的exe显示的是系统默认的白色窗口图案跟一堆乱码似的放在任何地方都显得特别不专业。哪怕你代码写得再干净别人第一眼看到这个白板图标心里就已经在打问号了。反过来换上一个像样的图标程序给人的感觉立刻就不一样了纯粹视觉层面的信任加分。这篇文章就是把这两件事彻底讲透。我默认你已经在用Qt6写代码了不管是QWidget还是QML都无所谓核心流程完全一致。文章里给的每一步、每一个命令行、每一段配置文件都是我在Windows上实测过的照着做就能出结果。同时我尽量把“为什么要这么做”也讲清楚免得你以后换个场景又抓瞎。2. 生成EXE全流程实操从构建到部署一步不落2.1 前提准备选对Qt套件与构建方式在动手之前先把“生成EXE”这件事拆成两个阶段编译阶段和部署阶段。编译阶段是把源文件变成exe部署阶段是往exe旁边塞一堆它运行所需的dll和插件。两个阶段分开理解后面就不容易乱。先说编译阶段。Qt6在Windows上的编译方式主要有两种用Qt Creator自带的构建功能或者用CMake命令行手动构建。不管哪种有个前提必须确认好——你当前选择的构建套件Kit是不是带“MinGW 64-bit”或者“MSVC 64-bit”字样以及构建配置是不是Release。很多新手习惯性用Debug模式跑测试到头来发现生成的exe体积巨大而且需要调试运行库这是第一层坑。我个人的习惯是日常开发调试用Debug等准备出包了新建一个目录专门做Release构建。在Qt Creator里操作很直观左下角选Release然后构建出来的exe在构建目录下的release/文件夹里。这一步没什么花哨的但要注意你的项目如果是CMake工程构建目录一般是build文件夹下的子目录千万别去源码目录里翻exe翻不到是因为构建产物跟源文件分开了。还有一处容易忽略你的程序如果用了Qt的某些模块比如Network、Sql那么发布时对应的dll也会被自动带出。这部分不用多操心windeployqt会处理但前提是你编译出的exe是完好的如果编译阶段就在报错那后边全是白忙。2.2 核心依赖收集工具windeployqt的正确用法这一步是整个发布流程的命门。Qt官方提供了一个工具叫windeployqt作用是把你的exe运行所需的Qt相关dll、插件、翻译文件全部复制到exe所在目录。它本质上就是个依赖扫描器加搬运工体量不大但少了它你几乎不可能手工凑齐那一堆dll。先找到windeployqt.exe的位置。如果你用的是在线安装的Qt6套件它通常在这个路径下D:\Qt\6.x.x\mingw_64\bin\windeployqt.exe注意这个路径跟你选择的编译套件是对应的。如果你用的是MSVC编译的exe那得用MSVC的那个bin目录下的windeployqt用MinGW编译的就找mingw_64目录下的。混着用不是一定不行但最容易出幺蛾子所以规则就是编译套件是谁windeployqt就用谁的。用法非常简单。先打开命令行把exe所在目录设为当前目录然后执行windeployqt --release --no-translations 你的程序名.exe加上--no-translations是因为我们的程序不需要Qt自带的语言文件省得生成一堆没用的qm文件。如果你的程序界面是中文硬编码显示的这个参数会帮目录清爽很多。另外如果你用了QML模块需要额外加--qmldir参数并指向你的qml源文件目录否则QML的插件不会被收集进去。一位朋友曾经在这个坑里卡了两天程序本地能跑发布后一启动就黑屏就是因为qml相关插件没带全。执行完之后exe目录里会多出几十个dll和文件夹这很正常别慌。关键检查两处platforms文件夹里有没有qwindows.dll以及styles文件夹里有没有qmodernwindowsstyle.dll这两个缺失任何一个程序都起不来。2.3 打包成单一EXE还是保留文件夹结构很多人的终极诉求是“把这个文件夹打成一个单文件exe扔给别人直接双击就能用”。这是个很正常的诉求但其实得泼一盆冷水——Qt程序几乎不可能靠一个exe就搞定所有依赖因为那几十个dll和插件是动态加载的强行塞成一个文件会引发各种奇怪问题。不过确实有替代方案用压缩软件自解压。把整个发布文件夹用7-Zip或WinRAR打包成一个自解压的exe解压到临时目录再运行。这种方案的好处是分享起来只有一个文件坏处是首次运行有延迟而且某些杀毒软件对自解压程序有额外的敏感度容易被误报。如果只是发给同事、朋友内部用完全可以如果是要做商业发布建议还是老老实实用文件夹结构配安装包。我一般用的是Inno Setup把整个发布目录做成安装程序。它免费、脚本配置起来也不难可以把dll、插件、exe全部塞进安装包装完后自动生成本地快捷方式。这个流程后面有机会单独写一篇这里先提个思路重点是先拿到一套能跑的发布目录。2.4 目录结构自查清单部署完成的目录应该是这个样子的以最简单的一个QWidget程序为例MyApp/ ├── MyApp.exe ├── platforminputcontexts/ ├── platforms/ │ └── qwindows.dll ├── styles/ ├── Qt6Core.dll ├── Qt6Gui.dll ├── Qt6Widgets.dll └── 其他若干dll...记一个简单的检查方法把目录拷到一台没有装Qt的虚拟机或者同事电脑上双击exe能正常弹窗就算过关。如果起不来先看命令行报错信息再根据后面第5章的排查表去对基本都能找到病根。3. 给EXE换一个正式图标让程序不再“白板”3.1 图标素材准备与ICO格式说明Windows的exe图标跟Linux不太一样Linux那边用PNG就行Windows这边必须用.ico格式。说“必须”可能有人不服气但事实就是图标资源编译阶段依赖的是ICO文件你拿一张PNG或JPG往工程里塞十有八九会失败或者显示空白。ICO格式最让人头疼的地方是它内部可以包含多张不同尺寸的图片从16x16小图标到256x256大图标都有Windows按需取用。比如任务栏用32x32桌面大图标模式用256x256如果ICO里没有对应尺寸系统会自动拉伸效果就糊了。所以准备图标时核心原则是图像素材尺寸至少得有256x256像素然后用工具导出成一整套ICO。推荐几个能用的办法在线转换搜索“png转ico”随便找一个大点的站点上传一张256x256的PNG选好尺寸集16、24、32、48、64、128、256导出ICO。ImageMagick命令行神器一条指令生成多尺寸ICOmagick convert icon_256.png -define icon:auto-resize256,128,64,48,32,16 icon.ico。Qt自家工具如果你装了Qt的IDE插件Qt Creator自带的资源编辑器也能导入svg转ico稍微绕一点。还有个坑必须提醒透明背景。如果你的图标素材带白底到了桌面那种深色壁纸上会非常难看。做图标时记得把背景抠干净导出PNG时保留透明通道再转ICO。3.2 编写RC资源文件Windows图标挂在哪个位置Qt工程跟Visual Studio的工程不太一样它不会自动帮你把ico加到exe里得自己写一个.rc资源文件然后在构建脚本里引用它。别被这个rc文件吓到内容就三五行。在最简单的场景下新建一个app.rc内容如下IDI_ICON1 ICON app_icon.icoIDI_ICON1是资源标识符随便起个名字都行只要别跟系统已占用的ID冲突就行一般不用太较真。后面跟的路径是ico文件相对于rc文件所在目录的路径为了稳妥建议把ico和rc放在同一个目录。如果你的工程用了qt官方模板rc文件通常已经建好名字一般叫app.rc或跟工程同名内容里可能已经有一行IDI_ICON1 ICON icon.ico你只需要把自己的ico文件替换进去就行不用重新写。3.3 CMake和qmake两种配置方式接下来是把rc文件挂到程序上的环节。先说CMake工程。Qt6官方推荐CMake配置文件里这样写set(APP_ICON_RESOURCE_WINDOWS app.rc) add_executable(MyApp main.cpp mainwindow.cpp ${APP_ICON_RESOURCE_WINDOWS} )核心就是把rc文件当成一个源文件追加到add_executable的源文件列表里。Windows平台的MSVC和MinGW都认这套写法CMake会自动把rc文件交给windres或rc编译器处理不需要你额外指定任何标志。如果你的CMake版本较新也可以写得更优雅一点if(WIN32) target_sources(MyApp PRIVATE app.rc) endif()这是推荐写法因为它在非Windows平台上会忽略rc文件不影响跨平台编译。再说qmake工程。QMake在Qt6里虽然不如CMake主流了但还有不少老项目在用。配置方法非常简单在.pro文件里加一行RC_FILE app.rc这种写法是Qt封装的变量qmake在Windows下会自动调用资源编译器。要注意的是qmake里也需要把ICO文件放到能被找到的位置一般放在工程根目录就能搜到。3.4 重新构建与效果验证配置完成后重新构建项目。构建产物在Windows下一般需要几分钟然后去release目录里看效果在资源管理器里exe文件的缩略图应该已经变成你设置的图标了。如果图标没变先别着急骂人Windows对exe图标是有缓存的。右键刷新没卵用的话试试重启资源管理器进程或者换个目录查看有时候需要重新登录一下系统才能刷掉旧缓存。把exe拷到别的电脑上看一眼如果那边显示正常说明rebuild时确实写进exe文件里了只是当前机器的图标缓存太顽固。另外有个小技巧可以验证图标到底有没有真正写进exe用资源管理器打开exe文件的“属性 - 详细信息”标签页里面如果有图标预览说明资源编译器确实干了活。这一步虽然不起眼但能帮你把问题归因到“代码配置”还是“Windows显示缓存”上排查效率会高很多。4. 常见的坑与排查技巧实录4.1 部署后exe双击没反应或闪退这是最经典的翻车现场。程序在开发环境里跑得好好的部署完换台机器就完蛋。逐个对照下面这些可能第一看有没有弹“缺少xxx.dll”的窗口。这个最常见于部署时windeployqt没能进到exe目录或者你根本没用过windeployqt就裸奔了。解药只有一个老老实实把windeployqt跑一遍。第二闪退没提示。这种通常是缺少平台插件。比如你复制exe时只复制了exe文件没复制整个文件夹那么Qt在启动时找不到platforms/qwindows.dll程序还没弹窗就崩了。判断方法也很简单把exe所在目录的platforms文件夹也一起拷过去。第三如果程序用了MySQL、PostgreSQL等数据库驱动或者某些第三方库别忘了它们同样有对应的dllwindeployqt不认识这些非Qt自带的dll需要手工复制。具体驱动文件有专门的命名规则别省这一步。第四排查环境就是换个用户账户、换台干净电脑测试。我之前帮人排查过一个“在家一切正常发给客户就闪退”的案例最后发现客户机器是32位系统而程序是64位的——架构不匹配神仙都救不了。4.2 windeployqt执行后又报缺特定dll有一些dll是Qt官方发布目录里带不出来的尤其是你在代码里用了某些旧模块比如Qt5兼容模块、专有模块或者链接了第三方闭源库。遇到这种情况最直接的办法是搜索你的Qt安装目录把对应的dll拷贝到exe目录下。不过我建议先搜清楚这个dll到底是干嘛的有些dll即使缺失程序也能正常跑因为没有真正调用到相关功能但带全总比带少强。另外windeployqt执行成功与否看输出日志末尾有没有“OK”之类的字样。有些中文环境下面日志信息是方言别被误导只要进程成功退出一般没问题。最可靠的方式还是测试运行。4.3 图标没变、显示旧图标或有白色默认图标图标问题的排查顺序大概是这样的先确认rc文件语法没毛病再看CMake/qmake配置里是否真把rc文件加进去了然后看重新构建过没有最后处理Windows缓存。这几个环节按顺序排除。有个隐蔽的坑是文件名带中文或空格。比如ico路径写成C:\我的图标 2.ico编译器有时会抽风。建议所有相关文件都用英文命名路径也尽量用英文。这不是技术洁癖是真的吃过亏。还有个非常容易被忽略的点如果你的CMake工程里同时存在主程序exe和其他可执行程序比如测试exe一定要确认改的是主程序那个target。有时候改了半天一看构建出来的exe是另一个测试工具图标能变才怪。4.4 发布前最后一道检查清单每次准备发新版我都会按这个清单过一遍Release模式重新构建确认构建日志无警告。windeployqt执行一遍观察终端输出无红色错误。检查platforms、imageformats、styles等关键目录存在。双击exe程序完整启动、退出无报错弹窗。在任务管理器里看进程名与版本号确认实际运行的是新版。把整个发布文件夹打个压缩包拷到另一台机器上做冒烟测试。这套流程大概十分钟就能走完但能拦下绝大多数低级事故。尤其那句“确认实际运行的是新版”听起来蠢但真的有好几次我以为自己构建成功了实际上跑的还是旧exe——因为构建目录跟发布目录搞混了。5. 再往深里走一步让EXE带上公司信息与版本号5.1 扩展rc文件把“看不见的细节”也补上exe文件的图标只是门面右键查看“属性”时那些版本信息、公司名称、产品描述同样影响别人对你程序的印象。这些信息也写在rc文件里以一个VS_VERSION_INFO块的形式存在。一个可用的rc文件模板大概是这样的1 VERSIONINFO FILEVERSION 1,0,0,1 PRODUCTVERSION 1,0,0,1 FILEOS 0x40004 FILETYPE 0x1 BEGIN BLOCK StringFileInfo BEGIN BLOCK 040904b0 BEGIN VALUE CompanyName, 你的公司名 VALUE FileDescription, 这个程序是干嘛的 VALUE FileVersion, 1.0.0.1 VALUE InternalName, MyApp VALUE OriginalFilename, MyApp.exe VALUE ProductName, 产品全名 VALUE ProductVersion, 1.0.0.1 END END BLOCK VarFileInfo BEGIN VALUE Translation, 0x409, 1200 END END把这个块加到rc文件里重新构建再查看exe属性就能看到一串正规的版本信息了。对Windows开发者来说这个细节往往能区分“业余作品”和“正经商用”。版本号这对于后续做自动更新、客户反馈问题定位都特别有用别等到要发第二个版本时才想起来补。5.2 使用Qt资源系统统一管理图标上面说的是exe自身的图标但很多程序运行起来之后界面上还有自己的Logo、工具栏图标、窗口小图标这些通常不写在rc文件里而是走Qt资源系统。做法是建一个.qrc文件把图片资源编进去然后在代码里通过:/images/logo.png这种路径引用。有些开发者弄不清楚rc和qrc的区别说“我明明在qrc里加了图标为啥exe图标还是白板”——因为它们是两套东西rc文件管exe的二进制资源影响的是文件管理器层面的图标qrc管的是Qt运行时能访问到的资源影响的是程序界面。两个都搞程序才完整。这里给个实操建议把不同用途的图标素材分目录存好assets/目录放qrc里用的界面图片resources/目录放rc里用的ico文件。千万别混在一起不然维护到后期找图找得想骂人。6. 我踩过几次坑之后的最终心得正好趁这个机会把压箱底的经验倒给你们。第一MinGW还是MSVC如果只在本机自娱自乐随便选一旦要发出去给别人用建议研究清楚目标用户的环境。MinGW版本的exe不需要装VC运行库对多数普通用户更省事MSVC版本的exe在Windows上兼容性更稳但目标机器可能需要装“Microsoft Visual C Redistributable”。两种方式没有绝对优劣你的选择直接影响发布包带不带“安装运行时”这一步。第二打包这件事越早越好。我第一次做发布包时项目已经写了一年半依赖了一堆第三方库结果windeployqt跑完之后还缺了十几个dll一个个手工排查简直要命。后来新项目我都是每加一个依赖库就顺手做一次发布环境的冒烟测试成本低到可以忽略好处却是能确保任何时候都能拿得出一份能跑的发布包。第三在发布目录里放一个README.txt写清楚这个包的版本号、构建日期、用了哪些第三方库的许可声明。别觉得这是形式主义等某天要回溯“这个exe到底是哪个commit构建出来的”时你会感谢当时多写的那几行字。第四备份windeployqt的目录模板。程序结构稳定后我会直接在构建机器上维护一份“最干净的发布文件夹”每到一个版本就把新exe丢进去替换旧exe跟发布相关的东西全都不动。这样既避免了每次发布时重复跑windeployqt又保证了发布目录的干净可靠。最后再多说一句如果按照这篇文章做完图标还是显示的旧样子先对着文件确认是不是构建后忘了复制如果复制了还这样再重启资源管理器或者注销一次Windows。这两个操作能解决九成以上的“图标没变”问题剩下的多半是你改错工程了。遇到过太多次这种乌龙写出来给你省点时间。
