Qt 6.4.0rc1提供了一种新思路同一个UI代码库既能编译成Windows原生EXE也能直接编译成WebAssembly在浏览器里跑。对于做桌面工具类软件、工业上位机界面或者想低成本把C/Qt遗产项目搬上Web的团队来说这比重写一个前端划算太多。这篇笔记围绕win10下的环境搭建把三个部分讲透Qt在线安装器的组件勾选、Emscripten工具链的版本匹配、Qt Creator里WebAssembly套件的配置流程。环境搭建最怕版本互相不认所以整篇采用“版本对齐优先”的策略凡是需要版本协同的地方都会明确标注跟着走一遍不会翻车。1. 版本选型逻辑为什么是Qt 6.4.0rc1和Emscripten 3.1.x先花点篇幅说清楚版本选择这是整篇的基础。如果版本没选对后面每一步都可能踩出奇怪报错。Qt对WebAssembly的支持不是从6.x才开始的5.11就有了基础支持5.15起已经比较成熟。Qt 6.0刚出的时候WebAssembly支持曾经回退过一段直到6.2 LTS才稳定下来6.4在6.2的基础上把整个wasm平台模块又重新打磨了一遍编译产出包更小模块裁剪也更灵活。我看到6.4.0rc1上线的消息时第一判断是WebAssembly模块的二进制已经比较接近最终发布形态用它来学习搭建流程不会白费功夫。这里要注意WebAssembly这个目标在Qt里不是开箱即用的它的官方支持方案是配合Emscripten来编译而不是像Windows桌面版那样用MSVC或MinGW就能直接编。Emscripten是C/C到wasm的编译器工具链Qt在浏览器里跑本质上是把Qt框架的源码和目标代码一起交给Emscripten最终产出一个Combined的wasm包。所以Qt版本和Emscripten版本之间存在严格的兼容关系写这篇验证用的组合是Windows 10 64位20H2及以上Qt 6.4.0 rc1Emscripten 3.1.14CMake 3.21Python 3.7Ninja构建工具为什么强调Emscripten要用3.1.14而不是最新版本Qt官方在发布Qt WebAssembly时会明确给出经过测试的Emscripten版本我当时查的是3.1.14这属于一个“官方注释过”的版本。如果装成Emscripten 3.1.15或更新的某些API签名有变化编译Qt源码时会出现头文件不匹配的报错。提示Emscripten是一个快速迭代的编译器项目每月可能出两三个小版本对Qt这类被编译对象来说“不追新追相对稳定”比什么都重要。浏览器方面也要提前说明WebAssembly最终运行环境是浏览器但我这篇只会涉及“编译产出”不会涉及复杂调试工具。本人日常Chrome 103以上Edge也可以Firefox 102以上同样没问题。手机端浏览器在这一版本下对wasm的多线程支持还有缺桌面Chrome调试wasm资源是最顺手的这是实操结果。2. 挑战与思路环境搭建的整体路径Qt WebAssembly环境搭建最大的难点不在Qt安装而在三个层次的协同Qt本身、Emscripten编译器、构建系统CMake与Ninja。不对齐这三层即使编译时侥幸过了运行时也可能出现wasm文件加载失败或Qt组件不可用。整个搭建路径分成五步安装基础的开发工具链Python、CMake、Ninja、Git安装Emscripten SDK并激活对应版本下载Qt 6.4.0rc1在线安装包并选择WebAssembly模块在Qt Creator中配置Emscripten编译器套件用一个小demo工程验证整个链路是否通畅这套顺序里Emscripten必须先装因为Qt安装时一般不会自动检查Emscripten但后续构建时自动检测它会依赖emcc命令的路径。如果反着装只是步骤颠倒问题不大但容易在Qt Creator配置阶段找不到编译器。最初我按照传统桌面开发的惯性思维先把Qt安装好再装Emscripten结果Qt Creator去em时什么都不显示排查了半天最后把Emscripten的emsdk_set_env.bat执行一遍后才正常。顺序倒过来再配置就非常快大约10分钟就能跑通HelloWorld。这也是这篇笔记刻意调整章节顺序的原因——工具链先行Qt安装在后顺着官方支持的依赖方向走。3. 环境搭建全流程一步一坑的记录3.1 基础开发工具CMake、Ninja、Python、GitQt 6.x已经全面转向CMake构建系统qmake虽然还能用但官方新特性优先都在CMake侧Ninja负责加速构建。所以这四样缺一不可。CMake直接下载官方二进制安装包Windows下注意勾选“Add CMake to the system PATH for all users”这个选项默认不勾。如果漏了后面在命令行执行cmake会提示命令不存在Qt Creator的自动检测也很可能失败。Ninja如果安装了Visual Studio可以用VS安装器里带的但我建议直接到Ninja的GitHub Release页面下载pre-built Windows压缩包解压后把ninja.exe所在目录添加到PATH。Ninja包很小几百KB不需要安装介质。PythonEmscripten的激活脚本是用Python写的Windows下建议用官方Python 3.10或3.11安装时勾选“Add Python to PATH”。这一步在很多“手把手教程”里都容易被忽略但Emscripten内嵌的脚本严重依赖Python环境变量。GitEmscripten SDK本身是通过Git拉取的推荐直接安装Git for Windows默认设置即可。所有基础工具装好后在命令行里依次验证一下cmake --version python --version ninja --version git --version四条命令都应该正常输出版本号。我是复用了之前做C开发时早已装好的环境你如果是第一次搭最好花3分钟验证这一点不然后面所有脚本都会在这里方向性地报错。3.2 编译三件套Emscripten SDK安装与版本锁定Emscripten的安装方式比较特殊它不是通过apt或者MSI安装而是通过Git克隆一个SDK仓库再用SDK自带的脚本去下载对应版本的二进制工具链。地址在GitHub的emscripten-core/emsdk仓库。克隆到本地时我一般会放在一个不带空格的路径下比如D:/emsdkWindows对带空格的长路径处理不够优雅后面激活环境变量时容易出问题。路径上尽量“住”成一个没有空格、没有中文的目录可以少踩很多坑。接下来是实操命令git clone https://github.com/emscripten-core/emsdk.git cd emsdk git pull emsdk.bat install 3.1.14 emsdk.bat activate 3.1.14重点说一下emsdk.bat activate。这一步并不是直接把Emscripten永久写入系统环境变量它所做的只是在本目录生成一个配置要在当前命令行窗口启用它还需要在clone下来的目录里执行emsdk_env.bat这个脚本会自动修改当前终端会话的环境变量。如果你关闭这个终端新的终端是不会自动带上emcc的。要全局生效需要手动在系统环境变量中加入Emscripten路径或者每次构建都用这个脚本初始化。Qt Creator里配置套件时它会直接读取这个路径所以为了使整个编辑器环境都能稳定的引入emcc建议手动把它写进系统环境变量D:/emsdk加上D:/emsdk/upstream/emscripten加上D:/emsdk/node/14.18.2_64bit/bin加上第三点是Emscripten内嵌Node.js的路径版本可能随你的SDK不同而变化打开emsdk目录看看node文件夹下面版本号是什么就填什么。激活完后验证emcc --version能输出类似emcc (Emscripten gcc/clang-like replacement) 3.1.14的信息说明正确。这里有一个非常容易被忽视的坑如果系统里装过MinGW或者其他GCC工具链PATH里的emcc信息可能会被另一个名字为emcc.bat或emcc.exe的同名程序干扰。如果你看到emcc --version输出的不是Emscripten版本直接检查PATH中是否存在其他emcc把Emscripten的路径调整到更靠前。3.3 下载Qt 6.4.0rc1组件选择与在线安装器问题Qt从5.15之后官方就不再提供离线安装了必须用在线安装器。访问Qt官网下载qt-unified-windows-x64-online.exe。这个安装器的好处是它本身是一个比较完整的安装向导能帮你选择组件问题是网络慢时特别容易让人心浮气躁。我个人经验是如果官网直接下载在线安装器的速度很慢可以使用国内镜像源很多大学的开源镜像站都同步了Qt的在线仓库安装器启动后需要在设置里添加一个临时Qt官方镜像的仓库地址。安装器启动后登录Qt账号。没有账号的话现场注册一个这个无法绕过。组件选择界面里按照Qt 6.4.0 rc1的目录树我的选择是展开Qt节点勾选Qt 6.4.0 RC1下的WebAssembly组件这个组件包含了wasm对应的Qt库和针对Emscripten编译所需的cmake配置同时勾选MinGW 11.2.0 64bit作为本地桌面调试工具链在“Developer and Designer Tools”节点下勾选Qt Creator、CMake、Ninja。在线安装器会顺便把你缺的工具一并装掉这里提醒一下Qt的WebAssembly组件在安装器里显示的版本号可能只是“Qt WebAssembly”并不会特别标出Emscripten版本需要对照官方支持列表。我装的时候勾选完占用的磁盘空间约3-4GBWebAssembly本身约800MB剩下的是MinGW和Qt Creator等工具占用的。对在线安装器偶尔会卡在某个组件上进度条长时间不动这种情况不要直接关闭安装器可以先取消当前下载组件数秒再点击重试会续传而不是从头开始。我安装过程中碰到过一次网络中断一直显示“Downloading Qt 6.4.0 RC1 WebAssembly”进度卡在67%很久我直接切换镜像源后重试才恢复。3.4 Qt Creator配置新建Emscripten套件安装成功后打开Qt Creator。进入Tools Options Kits Compilers点击添加编译器类型选择GCC编译器路径指向D:/emsdk/upstream/emscripten/em.bat。注意这里Qt Creator对Windows批处理文件的支持并不完美最好把编译器路径直接指向emcc.bat或em.bat所在目录而不是它内部实际的exe。再进入Qt Versions页面如果之前勾选了WebAssembly组件这里应该会有一个标注为Qt 6.4.0 RC1 WebAssembly的版本选择它并确认qmake路径指向的是wasm目录下的qmake而不是桌面版路径。如果同时装了桌面版和wasm版这里很容易选错。区分方式是路径wasm版本目录一般为6.4.0_rc1/wasm_single具体看安装器命名桌面版本目录为mingw_64或msvc2019_64。然后进入Kits页面新增一个套件名称Qt 6.4.0 RC1 WebAssembly编译器C和C都选Emscripten那一个emcc/emQt版本选择WebAssembly版本的QtCMake工具选择安装时自带的CMake调试器不需要配置浏览器调试不依赖GDB一切都配置好后套件前会显示一个绿色的勾至此Qt Creator侧的准备完成。3.5 快速验证编译第一个wasm的Hello World环境搭没搭好跑一个最小demo是最直接的验收方式。我在Qt Creator里新建了一个Qt Widgets ApplicationKit选择Qt 6.4.0 RC1 WebAssembly保留默认的带一个QPushButton的界面按钮点击弹出QMessageBox然后直接点击左下角的构建。第一次构建会比预想中慢因为需要把Qt的Widgets模块也编译进wasm中间会调用大量Emscripten编译任务我用的CPU是i5-10400大约花了3分钟。产出文件在构建目录下的wasm文件夹里核心是三个demo.html网页入口demo.jsQt加载器Javascript胶水代码demo.wasm编译出来的WebAssembly字节码文件这三个文件不能像普通网页一样双击用因为浏览器对wasm有跨域限制直接从file://协议打开会失败。正确姿势是在项目目录起一个本地HTTP服务python -m http.server 8000然后浏览器访问http://localhost:8000/demo.html如果看到窗口弹出来按钮点击有响应就说明环境搭建整体成功。注意如果访问时浏览器卡在加载界面、F12控制台显示TypeError: Failed to fetch dynamically imported module九成是路径问题检查HTML里的js和wasm文件是否放在同级目录或者HTTP服务是否把整个构建目录作为根目录。4. 常见报错与排查记录环境搭建过程中的坑非常多我把实际踩过的整理成一张速查表基本覆盖88%的问题。报错现象可能原因解决方案Command em not foundEmscripten没有激活或在PATH中找不到在emsdk目录执行emsdk_env.bat或检查PATHfatal error: QWidget file not foundQt Creator选的Qt版本是桌面版而不是wasm版打开Kit重新选择WebAssembly对应的Qt版本CMake报错找不到Qt6Config.cmakeCMake搜索路径里没有Qt的wasm模块在CMake配置中设置Qt6_DIR指向wasm版本Qt的lib/cmake/Qt6EMCC_WASM_BACKEND相关错误Emscripten版本过新或过旧重新激活与Qt匹配的Emscripten版本建议3.1.14emcc编译时出现missing binaryenEmscripten安装不完整二进制工具缺失删除emsdk目录重新clone安装网页加载后全白控制台无输出没有通过HTTP服务访问直接用本地文件打开的使用python -m http.server或其他静态服务器编译进度永远卡在一个文件上且CPU不高可能是杀毒软件扫描wasm编译中间文件拖慢把emsdk和Qt的目录加入杀毒软件白名单或者临时退出文件筛选扫描链接时报错wasm-ld: error: unknown argument: --reproduce当前Emscripten版本与CMake工具配置的链接参数不匹配把CMake/Ninja更新到Qt官方要求的最低版本下面挑两个最值得展开的报错说明排查逻辑。第一个是“Kit配置好但构建时找不到编译器”的问题。Qt Creator虽然能从em自动推断编译器但如果你先安装了MinGWQt Creator很容易把默认编译器关联到MinGW的g上去构建时就会报QT WASM requires Emscripten compiler。解决方式是手动编辑Kit把C编译器和C编译器都明确指定为emcc.bat和em.bat而不是靠自动检测。这是最容易误导新人的地方因为界面上“自动检测”看起来正确但实际选了错误的工具链。第二个是CMake侧的问题。Qt 6的CMake配置默认会尝试找本机已安装的Qt包如果你系统里另外装了桌面版Qt在构建时CMake缓存可能指向桌面版路径导致接下来所有模块都是桌面版目标链接阶段疯狂报错。清晰快捷的方式是删除构建目录内的CMakeCache.txt重新用Qt Creator构建确保构建时用了对应Kit的QMake路径。受够这个问题的开发者还可以使用命令行直接指定cmake -DCMAKE_PREFIX_PATHD:/Qt/6.4.0_rc1/wasm_single5. 环境验证后的进阶配置运行器与浏览器调试选项HelloWorld跑通后如果打算在这个环境上认真做开发建议把Qt Creator的运行配置也顺手调好。之前用默认配置时Qt Creator会调用系统默认浏览器打开那个HTML但某些情况下会报错“无法找到可执行文件”。原因是对于wasm目标Qt Creator没有与浏览器对应的Run配置。解决方式是在Qt Creator的Projects Run页面为当前项目创建一个自定义的可执行配置可执行文件指向python.exe前面装好的Python命令行参数-m http.server 8000工作目录设置为构建产物HTML所在目录这样做的好处是以后每次按运行按钮Qt Creator会帮你构建、起服务、打开默认浏览器访问页面不用在终端里手动敲命令省下大量时间。Browser Debugging方面Qt 6.4.0rc1的wasm构建默认是用-g调试信息的但浏览器里直接断点调试Qt源码还是比较受限。更实用的调试手段反而是在代码里加qDebug()输出在浏览器控制台里能看到日志因为Qt的日志系统会默认输出到浏览器console。这一步对排查业务逻辑问题很有效。6. 环境搭建完成后的个人体会整套环境搭完之后再回头看每一步的“绊脚石”多半出在“版本匹配”和“环境变量”上。Emscripten本身是一个快速变化的编译器Qt WebAssembly又是在Qt大版本基础上派生出的特化目标两者只要差一个小的minor版本就可能在新API上产生范围很大的不兼容。如果把时间拉长看最优实践就是把Emscripten版本固定到和Qt官方测试用的版本然后不再动它除非Qt也要跟着升级。另外Qt WebAssembly组件的构建产物对部署方式非常挑剔它要求所有资源都通过HTTP服务访问部署到CDN时需要对.wasm文件的Content-Type做配置。标准静态服务器一般都能正确处理但如果你用自己写的后端服务托管这些文件需要保证application/wasm这个MIME类型被正确设置否则浏览器会拒绝执行。还有一点是Windows平台特有的。Qt安装器的在线下载常常比Linux和macOS上更不稳定如果你在下载Qt组件时遇到反复失败先检查系统代理设置再判断是不是杀毒软件对安装器的实时扫描导致网络超时。把Qt目录加入白名单不仅解决下载速度也解决后续wasm编译时频繁IO导致的构建时间异常长。这套环境搭好之后后续可以开始尝试把比较复杂的QWidget成品项目编译到浏览器里跑尤其是之前积累了几年C业务代码的移植时改动量一般远小于前端的重写。我下一步的计划是拿一个内部工具软件试水看看核心逻辑部分在wasm环境下与原生环境的性能差距到底有多大到时有实测数据再回来更新系列的下一篇。