前几篇笔记都在聊概念和踩坑这篇算是环境篇的收官——把 win10 下 Qt 6.4.0 rc1 WebAssembly 开发环境从零到一完整搭起来的全过程整理成文。这套环境的本质是把 C 写的 Qt 应用通过 Emscripten 工具链交叉编译成 WebAssembly 字节码让桌面程序直接跑进浏览器。我在实际搭的过程中发现Qt for WebAssembly 的坑并不在 Qt 本身而在编译器工具链的版本匹配、环境变量、浏览器安全策略这些边角料上。所以这篇不仅会给出每一步操作还会把每个“为什么这么做”一并讲清楚新手照着做基本一个小时能跑出第一个页面。1. 为什么要在 win10 上折腾这套 Qt 与 WebAssembly 环境1.1 WebAssembly 是什么Qt 为什么能往浏览器里跑很多朋友第一次听说 WebAssembly 时都会问同一个问题C 编译出来的程序怎么可能在浏览器里运行这里有个关键概念需要先理清。WebAssembly 本质上是一种字节码标准浏览器内置了对应的虚拟机可以直接执行这种字节码。但问题在于普通 C 代码并不能直接编译成 wasm它需要一套完整的交叉编译链把 C 源码、标准库、以及依赖的第三方库全部编译成 wasm 形态。这就是 Emscripten 的活儿。Emscripten 基于 LLVM 的 clang 前端把 C 编译成 wasm 字节码同时生成一层 JavaScript 胶水代码负责内存管理、模块加载、和浏览器 API 的桥接。而 Qt 本身是 C 框架理论上只要 Qt 库能编译成 wasmQt 应用就能跑在浏览器里。Qt 官方从 Qt 6.2 开始正式支持 WebAssembly 平台安装 Qt 时勾选对应组件就会自动装上编译好的 wasm 版 Qt 库。理解了这层原理你就会明白为什么环境搭建是这个技术方向的第一道坎。正常桌面开发只需要 Qt 安装包加一个编译器而 WebAssembly 开发需要额外准备一整套 Emscripten 工具链还要确保 Qt 版本和 Emscripten 版本互相兼容。版本不对编译时各种诡异报错能把你折腾到怀疑人生。1.2 版本取舍6.4.0 rc1 与匹配的 Emscripten我当时选择 6.4.0 rc1不是拍脑袋决定的主要看到了两个点。第一Qt 6.4 对 WebAssembly 平台的完善度比 6.2、6.3 高出一截尤其是多线程支持、Qt Quick 性能、文件系统访问等关键能力都有明显改进第二rc1 是候选发布版功能已经冻结距离正式版只差 bug 修复拿来学习预研完全够用。但这里必须清醒一点rc 是“Release Candidate”的缩写它不是稳定版官方不推荐在生产环境使用。我选择它的原因纯粹是想提前体验新特性如果你追求稳定建议直接等正式版。另外要注意 Qt 与 Emscripten 的版本对应关系Qt 6.4.0 官方要求的最低 Emscripten 版本是 3.1.14我实测 3.1.14 以及其后的小版本都能正常工作。低于这个版本编译 Qt 模块时会直接报错基本没有回旋余地。2. 环境搭建前的准备工作2.1 win10 系统基础要求与目录规划先说硬件和系统层面。win10 系统版本建议 1809 以上内存在 8G 左右就够用但如果你是首次编译大项目16G 会更从容。磁盘空间方面Emscripten 工具链大约占 3~5GQt 6.4.0 的 WebAssembly 组件加上基础模块大约占 6~8G加上构建缓存建议至少预留 20G 空余。整个搭建过程中最容易忽略也最容易出问题的是目录命名。Qt 官方安装目录默认在C:\Qt这没问题。但 Emscripten 的 SDK 目录我强烈建议不要带中文、不要带空格。比如D:\QtCode\emsdk这种纯英文路径背后原因很现实Emscripten 的编译脚本是 Python 写的在处理中文字符路径时经常出现编码问题而 Windows 下的各种命令行工具对含空格路径的处理也容易出岔子。我当时因为把项目放在一个带中文的目录下emcc 编译阶段报了一个让人摸不着头脑的错误排查了半天才意识到是路径问题。另外一个很多人不会告诉你但实操中很影响体验的点Windows Defender 的实时防护会在编译时频繁扫描生成的临时文件wasm 首次链接时会产生大量临时文件扫描器介入会让编译时间翻倍。解决办法不是关闭安全中心而是把 Qt 安装目录、emsdk 目录、以及项目构建目录加入 Defender 的排除列表只针对这几个目录加白名单既安全又高效。2.2 工具链清单与下载准备开始之前我先把整套环境需要的组件列清楚避免装到一半发现缺东西。组件用途获取方式Git for Windows拉取 Emscripten SDK 仓库git-scm.com 官方安装包Python 3.xEmscripten 工具链的运行时依赖python.org 官方安装包Emscripten SDK (emsdk)编译 C 到 WebAssembly 的核心工具链通过 git clone 获取仓库Qt 6.4.0 rc1Qt 框架本体及 WebAssembly 预编译库Qt 官方在线安装器Qt Creator图形化 IDE配置编译套件和调试随 Qt 在线安装器勾选Python 和 Git 的安装比较简单一路 Next 就行唯一要注意的是安装 Python 时记得勾选“Add Python to PATH”。Git 安装时默认选项即可不需要额外配置。接下来是时序问题。我的建议是先把 emsdk 装好再装 Qt因为 Qt Creator 首次启动时会自动探测 PATH 中的编译器如果 emsdk 已经激活Creator 就能自动识别出 WebAssembly 工具链省去手动配置的麻烦。反过来如果先装 Qt 再配 emsdkCreator 的自动识别通常还是能生效但偶尔需要手动刷新一下体验不如前者顺畅。3. Emscripten 工具链安装与激活3.1 获取 emsdk 并安装指定版本打开命令提示符或 PowerShell进入你规划好的目录比如D:\QtCode执行以下命令git clone https://github.com/emscripten-core/emsdk.git cd emsdk git pull克隆完成后emsdk 目录下会看到一个emsdk.bat脚本这是 Windows 下的主要操作入口。接下来安装指定版本的 Emscriptenemsdk install 3.1.14这一步会下载并安装完整的工具链包括 clang、node.js、binaryen 等组件。下载体积大约是几百 MB 到 1G 左右具体取决于网络状况。这里有一个新手容易踩的坑emsdk install执行到一半如果报网络错误不要反复重试先检查网络是否稳定。我当时遇到的情况是下载了 80% 左右连接中断重试后它不会断点续传必须从零开始白白等了两次。后来学到的经验是让它一次跑完期间不要动网络不要切换 WiFi更不要开浏览器占用大量带宽。如果下载速度实在不行也可以试试换一个时间段再跑挑网络空闲的时候成功率会高很多。安装完成后执行激活emsdk activate 3.1.14activate 的作用是生成当前 SDK 版本的配置文件并且会把这个版本设置为默认版本。这一步执行完只是完成了当前终端会话的环境准备并没有把环境变量写入系统。如果你希望每次打开新终端都能直接使用 emcc 命令还需要运行emsdk_env.bat这条命令会把 Emscripten 的 bin 目录、node 目录等加入当前会话的 PATH。如果只想在当前窗口临时用执行一次即可想永久生效可参考下面的验证部分。3.2 环境变量与验证环境变量的配置是整个环境搭建中最关键的一步我来详细说明。emsdk_env.bat只在当前终端窗口生效关闭终端后环境就失效了。为了让整个系统的所有终端都能调用 emcc我推荐使用永久配置方式。在 emsdk 目录下有一个emsdk.bat它支持一个隐藏参数emsdk activate --permanent 3.1.14执行这条命令后Emscripten 会把必要的环境变量写入 Windows 用户级别的注册表之后新开的终端、以及 Qt Creator 这类图形界面程序都能自动识别到 Emscripten 工具链。这是我在踩过几次坑之后总结出的最省心做法。配置完成后开一个新终端验证emcc --version如果能看到 emcc 的版本号以及 “emcc (Emscripten gcc/clang-like driver)” 字样说明工具链已经就绪。我还会顺手验证一下 Python 环境python --version确保 Python 版本是 3.x 即可。我这里给一个合理建议验证环境变量是否生效时一定要重新开一个新的终端窗口而不是在旧窗口里运行——Windows 的环境变量是在进程启动时读取的旧窗口不会动态刷新这是新手最容易误判环境没配好的原因。4. Qt 6.4.0 rc1 安装与组件勾选4.1 在线安装器与组件选择Qt 官方提供两种安装方式在线安装器和离线安装包。在线安装器支持自定义组件勾选、随时增删模块是这个场景下的最优选择。一个重要提示6.4.0 rc1 属于预发布版本在线安装器默认不会显示它你需要在安装器的“Settings”里勾选“Show preview versions”之类的预览选项然后在组件列表的 Qt 6.4.0 RC1 分类下才能看到它。Qt 安装器需要登录 Qt 账号。这个账号是免费的在 Qt 官网注册一下即可不需要付费订阅就能使用开源版的安装组件。如果你在安装器登录环节遇到网络波动导致登录失败建议换个网络环境再试。组件勾选是这个环节的核心。我推荐按下面这个清单来选Qt 6.4.0 RC1 分类下的 WebAssemblysingle-threaded和 WebAssemblymulti-threaded组件这是跑 WebAssembly 的核心库必须勾选。Additional Libraries 分类下的 Qt 5 Compatibility Module方便后续使用一些 Qt 5 时代的 API。Qt Creator 本体以及 Qt Debugger 工具装好后直接集成到 IDE 里。如果之后想在桌面上联调逻辑顺手勾选一个 MinGW 11.2.0 编译器但这不是 WebAssembly 必需的。需要特别留意的是Qt 6.4 开始不再在安装器中捆绑 OpenSSL 动态库这对 WebAssembly 场景影响不大因为 wasm 版 Qt 的网络请求通常直接走浏览器 fetch API。当时我在勾选组件时第一反应想把 Sources 源码也勾上后来发现它对编译没有影响但调试时看 Qt 源码非常有帮助磁盘空间够的话建议勾上。4.2 安装后目录结构与验证安装完成后Qt 的目录结构大概长这样C:\Qt\ 6.4.0\ wasm_singlethread\ bin\qmake.exe lib\ qml\ wasm_multithread\ bin\qmake.exe lib\ qml\ Tools\wasm_singlethread对应单线程版本wasm_multithread对应多线程版本。多线程版本依赖浏览器的 SharedArrayBuffer 能力部署时要求服务器配置跨源隔离响应头所以日常学习和调试我建议默认用单线程版本跑通了再尝试多线程。验证安装是否成功最直接的办法是查看 wasm 版本 qmake 是否存在C:\Qt\6.4.0\wasm_singlethread\bin\qmake.exe -v如果 qmake 能输出版本信息说明 Qt 的 WebAssembly 库已经正确安装。这一步验证很重要因为后续 Qt Creator 的 Kit 配置中需要把这个 qmake 路径手动指给 IDE。5. Qt Creator 套件配置与编译验证5.1 配置 WebAssembly 编译套件打开 Qt Creator正常情况下它会自动检测到 Emscripten 工具链和 Qt 的 WebAssembly 版本。你可以在“工具”-“选项”-“Kits”页面看到类似“Qt 6.4.0 WebAssembly”的条目标签。如果没看到不要慌大概率是环境变量没被 Creator 读到手动配置即可。手动配置步骤进入“选项”-“Kits”-“编译器”点击“添加”-“Clang”然后选择 C 编译器为 emsdk 目录下的 em 脚本。以我的安装路径为例C:\QtCode\emsdk\upstream\emscripten\em.bat这里有个细节容易踩坑Qt Creator 识别编译器时需要分别添加 C 编译器和 C 编译器。C 编译器选emcc.batC 编译器选em.bat。如果你只添加了 C 编译器部分 CMake 项目在配置阶段会因找不到 C 编译器而报错。接着在“Kits”页面点击“添加”新建一个编译套件。套件名称随意比如“Qt 6.4.0 WebAssembly”然后在“编译器”下拉框中选择刚添加的 emcc/em“Qt version”下拉框中选择 wasm_singlethread 对应的 qmake。保存后这个 Kit 就会出现在项目构建套件列表里。这里再补充一个坑如果你在 Creator 已经打开的情况下才执行了 emsdk 的永久激活命令需要完全退出 Qt Creator 再重新打开它才会重新读取环境变量。只关项目不关 IDE 是不生效的我因为这个白等了十几分钟。5.2 创建并编译第一个 WebAssembly 工程套件配置完成后新建一个工程测试“文件”-“新建项目”选择“Qt Quick Application”模板。项目名称和路径都用纯英文比如D:\QtCode\hello_wasm。在“构建套件选择”页面勾选上一步创建的“Qt 6.4.0 WebAssembly”套件。点击“完成”后先不要急着改代码保持模板自带的窗口和按钮。直接点击左下角的“构建”按钮。第一次编译会比较慢我记得当时等了大约五到八分钟期间终端输出各种编译信息看起来像是卡住了。这其实是正常的因为要把 Qt 的 wasm 库和应用代码一起链接成最终的 wasm 文件链接阶段特别耗时。如果你的杀毒软件在运行这个时间还会更长。编译完成后在构建输出目录下会生成三个关键产物文件名作用hello_wasm.html网页入口文件包含页面结构和加载逻辑hello_wasm.jsJavaScript 胶水代码负责加载 wasm 模块和内存管理hello_wasm.wasm真正的 WebAssembly 字节码包含编译后的 C 代码5.3 本地部署与文件结构编译完成但不代表能直接双击 html 查看效果。WebAssembly 模块的加载依赖 fetch 等浏览器 API而浏览器安全策略禁止在file://协议下执行这类请求。所以你打开hello_wasm.html时会得到一个白屏页面控制台报 net::ERR_FILE_NOT_FOUND。正确的做法是把这三个文件放到一个本地 HTTP 服务器上。最简单的方式是用 Python 自带的服务cd D:\QtCode\build-hello_wasm-... python -m http.server 8000然后在浏览器访问http://localhost:8000/hello_wasm.html。如果看到 Qt Quick 默认窗口说明整条链路已经通了。Qt Creator 本身也带了运行机制直接点击“运行”按钮Creator 会启动一个内置的本地服务器并自动打开浏览器省去手动起服务的步骤。我建议你两种方式都试一遍因为后续真正部署到线上环境时你会需要理解静态服务器的那套逻辑。有几点部署时需要注意静态服务器的 MIME 类型必须包含application/wasm否则浏览器会拒绝加载 wasm 文件如果是多线程版本还需要后端配置Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp这两个响应头否则 SharedArrayBuffer 会被浏览器拦截。这些都是我在实际部署时踩过的坑默认配置下必然踩提前知道能省不少时间。6. 常见问题与排查技巧实录6.1 高频报错速查表整个搭建过程中我收集了一批高频问题整理成下表基本覆盖了新手会遇到的 90% 的情况现象原因解决办法Kit 列表里没有 WebAssembly 选项安装 Qt 时没勾选 WebAssembly 组件重跑 Qt 在线安装器勾选 WebAssembly 后重新安装编译时提示“emcc 不是内部或外部命令”Emscripten 环境变量未生效重新执行 emsdk activate --permanent重启终端和 Qt Creator网页白屏控制台报 ERR_FILE_NOT_FOUND直接用 file:// 打开了 html改用本地 HTTP 服务器访问wasm 加载失败提示不支持的 MIME 类型服务器没配置 application/wasm修改静态服务器配置加 MIME 类型多线程版运行时报 SharedArrayBuffer is not defined缺少跨源隔离响应头配置 COOP/COEP或先用单线程版本首次编译慢到像死机Qt wasm 库链接耗时长耐心等同时把 Qt 目录和 emsdk 目录加入杀软白名单编译报路径不存在或文件找不到项目路径包含中文字符把项目移到纯英文路径重新构建6.2 我踩过的三个坑第一个坑是中文路径问题。我当时图省事把项目放在D:\工作\学习\hello_wasm下emcc 编译时报了一个编码错误报错信息看了半天没看懂。后来把项目移到D:\QtCode\hello_wasm后一切正常。从那次之后我所有涉及交叉编译的项目一律纯英文路径这个习惯帮我避掉了后面很多麻烦。第二个坑是缓存问题。我中途升级过 Qt 的 RC 版本结果浏览器还在加载旧的 qtloader.js 缓存页面上的按钮点击后没有任何响应。排查了半天最后强制刷新浏览器并删除项目 build 目录重新编译才解决。这个问题的隐蔽性在于编译成功、页面也能打开但运行时行为异常非常容易误导排查方向。第三个坑是 Qt Creator 检测不到 emsdk。原因是当时偷懒只在当前终端执行了emsdk_env.bat压根没做永久激活。这种情况下从桌面图标打开的 Qt Creator 读不到 Emscripten 的环境变量编译器列表里自然找不到 emcc。后来我改用emsdk activate --permanent永久写入环境变量并重启了 IDE问题才彻底消失。结合这三个坑我给后来者的一个总结性建议环境搭建阶段不要把时间花在“看起来能用”上而是要做到“任何新终端都能用”。把你的 emsdk 环境变量做成永久生效项目目录全部纯英文构建缓存该清理就清理这三点前置做到位后续的学习效率会高很多。最后再多说一句我的个人体会。Qt for WebAssembly 这套东西真正跑通之后最让人惊喜的是“一套代码双端运行”的体验——同一个 Qt 工程切换到桌面套件编译就是 exe切换到 WebAssembly 套件编译就是网页。从这个环境跑通之后我陆续把一些 Qt 界面里的英文文案接上了 qt 国际化把耗时逻辑的进度反馈用自定义进度条做成了网页可视化效果都超出预期。不过这些都是从今天这个基础环境延伸出来的后续话题留着下一篇笔记接着写吧。 
长河君 · 2026/9/15 12:09:26 · 阅读 1.2k Win10搭建Qt 6.4.0 WebAssembly环境：从零配置Emscripten工具链
前几篇笔记都在聊概念和踩坑这篇算是环境篇的收官——把 win10 下 Qt 6.4.0 rc1 WebAssembly 开发环境从零到一完整搭起来的全过程整理成文。这套环境的本质是把 C 写的 Qt 应用通过 Emscripten 工具链交叉编译成 WebAssembly 字节码让桌面程序直接跑进浏览器。我在实际搭的过程中发现Qt for WebAssembly 的坑并不在 Qt 本身而在编译器工具链的版本匹配、环境变量、浏览器安全策略这些边角料上。所以这篇不仅会给出每一步操作还会把每个“为什么这么做”一并讲清楚新手照着做基本一个小时能跑出第一个页面。1. 为什么要在 win10 上折腾这套 Qt 与 WebAssembly 环境1.1 WebAssembly 是什么Qt 为什么能往浏览器里跑很多朋友第一次听说 WebAssembly 时都会问同一个问题C 编译出来的程序怎么可能在浏览器里运行这里有个关键概念需要先理清。WebAssembly 本质上是一种字节码标准浏览器内置了对应的虚拟机可以直接执行这种字节码。但问题在于普通 C 代码并不能直接编译成 wasm它需要一套完整的交叉编译链把 C 源码、标准库、以及依赖的第三方库全部编译成 wasm 形态。这就是 Emscripten 的活儿。Emscripten 基于 LLVM 的 clang 前端把 C 编译成 wasm 字节码同时生成一层 JavaScript 胶水代码负责内存管理、模块加载、和浏览器 API 的桥接。而 Qt 本身是 C 框架理论上只要 Qt 库能编译成 wasmQt 应用就能跑在浏览器里。Qt 官方从 Qt 6.2 开始正式支持 WebAssembly 平台安装 Qt 时勾选对应组件就会自动装上编译好的 wasm 版 Qt 库。理解了这层原理你就会明白为什么环境搭建是这个技术方向的第一道坎。正常桌面开发只需要 Qt 安装包加一个编译器而 WebAssembly 开发需要额外准备一整套 Emscripten 工具链还要确保 Qt 版本和 Emscripten 版本互相兼容。版本不对编译时各种诡异报错能把你折腾到怀疑人生。1.2 版本取舍6.4.0 rc1 与匹配的 Emscripten我当时选择 6.4.0 rc1不是拍脑袋决定的主要看到了两个点。第一Qt 6.4 对 WebAssembly 平台的完善度比 6.2、6.3 高出一截尤其是多线程支持、Qt Quick 性能、文件系统访问等关键能力都有明显改进第二rc1 是候选发布版功能已经冻结距离正式版只差 bug 修复拿来学习预研完全够用。但这里必须清醒一点rc 是“Release Candidate”的缩写它不是稳定版官方不推荐在生产环境使用。我选择它的原因纯粹是想提前体验新特性如果你追求稳定建议直接等正式版。另外要注意 Qt 与 Emscripten 的版本对应关系Qt 6.4.0 官方要求的最低 Emscripten 版本是 3.1.14我实测 3.1.14 以及其后的小版本都能正常工作。低于这个版本编译 Qt 模块时会直接报错基本没有回旋余地。2. 环境搭建前的准备工作2.1 win10 系统基础要求与目录规划先说硬件和系统层面。win10 系统版本建议 1809 以上内存在 8G 左右就够用但如果你是首次编译大项目16G 会更从容。磁盘空间方面Emscripten 工具链大约占 3~5GQt 6.4.0 的 WebAssembly 组件加上基础模块大约占 6~8G加上构建缓存建议至少预留 20G 空余。整个搭建过程中最容易忽略也最容易出问题的是目录命名。Qt 官方安装目录默认在C:\Qt这没问题。但 Emscripten 的 SDK 目录我强烈建议不要带中文、不要带空格。比如D:\QtCode\emsdk这种纯英文路径背后原因很现实Emscripten 的编译脚本是 Python 写的在处理中文字符路径时经常出现编码问题而 Windows 下的各种命令行工具对含空格路径的处理也容易出岔子。我当时因为把项目放在一个带中文的目录下emcc 编译阶段报了一个让人摸不着头脑的错误排查了半天才意识到是路径问题。另外一个很多人不会告诉你但实操中很影响体验的点Windows Defender 的实时防护会在编译时频繁扫描生成的临时文件wasm 首次链接时会产生大量临时文件扫描器介入会让编译时间翻倍。解决办法不是关闭安全中心而是把 Qt 安装目录、emsdk 目录、以及项目构建目录加入 Defender 的排除列表只针对这几个目录加白名单既安全又高效。2.2 工具链清单与下载准备开始之前我先把整套环境需要的组件列清楚避免装到一半发现缺东西。组件用途获取方式Git for Windows拉取 Emscripten SDK 仓库git-scm.com 官方安装包Python 3.xEmscripten 工具链的运行时依赖python.org 官方安装包Emscripten SDK (emsdk)编译 C 到 WebAssembly 的核心工具链通过 git clone 获取仓库Qt 6.4.0 rc1Qt 框架本体及 WebAssembly 预编译库Qt 官方在线安装器Qt Creator图形化 IDE配置编译套件和调试随 Qt 在线安装器勾选Python 和 Git 的安装比较简单一路 Next 就行唯一要注意的是安装 Python 时记得勾选“Add Python to PATH”。Git 安装时默认选项即可不需要额外配置。接下来是时序问题。我的建议是先把 emsdk 装好再装 Qt因为 Qt Creator 首次启动时会自动探测 PATH 中的编译器如果 emsdk 已经激活Creator 就能自动识别出 WebAssembly 工具链省去手动配置的麻烦。反过来如果先装 Qt 再配 emsdkCreator 的自动识别通常还是能生效但偶尔需要手动刷新一下体验不如前者顺畅。3. Emscripten 工具链安装与激活3.1 获取 emsdk 并安装指定版本打开命令提示符或 PowerShell进入你规划好的目录比如D:\QtCode执行以下命令git clone https://github.com/emscripten-core/emsdk.git cd emsdk git pull克隆完成后emsdk 目录下会看到一个emsdk.bat脚本这是 Windows 下的主要操作入口。接下来安装指定版本的 Emscriptenemsdk install 3.1.14这一步会下载并安装完整的工具链包括 clang、node.js、binaryen 等组件。下载体积大约是几百 MB 到 1G 左右具体取决于网络状况。这里有一个新手容易踩的坑emsdk install执行到一半如果报网络错误不要反复重试先检查网络是否稳定。我当时遇到的情况是下载了 80% 左右连接中断重试后它不会断点续传必须从零开始白白等了两次。后来学到的经验是让它一次跑完期间不要动网络不要切换 WiFi更不要开浏览器占用大量带宽。如果下载速度实在不行也可以试试换一个时间段再跑挑网络空闲的时候成功率会高很多。安装完成后执行激活emsdk activate 3.1.14activate 的作用是生成当前 SDK 版本的配置文件并且会把这个版本设置为默认版本。这一步执行完只是完成了当前终端会话的环境准备并没有把环境变量写入系统。如果你希望每次打开新终端都能直接使用 emcc 命令还需要运行emsdk_env.bat这条命令会把 Emscripten 的 bin 目录、node 目录等加入当前会话的 PATH。如果只想在当前窗口临时用执行一次即可想永久生效可参考下面的验证部分。3.2 环境变量与验证环境变量的配置是整个环境搭建中最关键的一步我来详细说明。emsdk_env.bat只在当前终端窗口生效关闭终端后环境就失效了。为了让整个系统的所有终端都能调用 emcc我推荐使用永久配置方式。在 emsdk 目录下有一个emsdk.bat它支持一个隐藏参数emsdk activate --permanent 3.1.14执行这条命令后Emscripten 会把必要的环境变量写入 Windows 用户级别的注册表之后新开的终端、以及 Qt Creator 这类图形界面程序都能自动识别到 Emscripten 工具链。这是我在踩过几次坑之后总结出的最省心做法。配置完成后开一个新终端验证emcc --version如果能看到 emcc 的版本号以及 “emcc (Emscripten gcc/clang-like driver)” 字样说明工具链已经就绪。我还会顺手验证一下 Python 环境python --version确保 Python 版本是 3.x 即可。我这里给一个合理建议验证环境变量是否生效时一定要重新开一个新的终端窗口而不是在旧窗口里运行——Windows 的环境变量是在进程启动时读取的旧窗口不会动态刷新这是新手最容易误判环境没配好的原因。4. Qt 6.4.0 rc1 安装与组件勾选4.1 在线安装器与组件选择Qt 官方提供两种安装方式在线安装器和离线安装包。在线安装器支持自定义组件勾选、随时增删模块是这个场景下的最优选择。一个重要提示6.4.0 rc1 属于预发布版本在线安装器默认不会显示它你需要在安装器的“Settings”里勾选“Show preview versions”之类的预览选项然后在组件列表的 Qt 6.4.0 RC1 分类下才能看到它。Qt 安装器需要登录 Qt 账号。这个账号是免费的在 Qt 官网注册一下即可不需要付费订阅就能使用开源版的安装组件。如果你在安装器登录环节遇到网络波动导致登录失败建议换个网络环境再试。组件勾选是这个环节的核心。我推荐按下面这个清单来选Qt 6.4.0 RC1 分类下的 WebAssemblysingle-threaded和 WebAssemblymulti-threaded组件这是跑 WebAssembly 的核心库必须勾选。Additional Libraries 分类下的 Qt 5 Compatibility Module方便后续使用一些 Qt 5 时代的 API。Qt Creator 本体以及 Qt Debugger 工具装好后直接集成到 IDE 里。如果之后想在桌面上联调逻辑顺手勾选一个 MinGW 11.2.0 编译器但这不是 WebAssembly 必需的。需要特别留意的是Qt 6.4 开始不再在安装器中捆绑 OpenSSL 动态库这对 WebAssembly 场景影响不大因为 wasm 版 Qt 的网络请求通常直接走浏览器 fetch API。当时我在勾选组件时第一反应想把 Sources 源码也勾上后来发现它对编译没有影响但调试时看 Qt 源码非常有帮助磁盘空间够的话建议勾上。4.2 安装后目录结构与验证安装完成后Qt 的目录结构大概长这样C:\Qt\ 6.4.0\ wasm_singlethread\ bin\qmake.exe lib\ qml\ wasm_multithread\ bin\qmake.exe lib\ qml\ Tools\wasm_singlethread对应单线程版本wasm_multithread对应多线程版本。多线程版本依赖浏览器的 SharedArrayBuffer 能力部署时要求服务器配置跨源隔离响应头所以日常学习和调试我建议默认用单线程版本跑通了再尝试多线程。验证安装是否成功最直接的办法是查看 wasm 版本 qmake 是否存在C:\Qt\6.4.0\wasm_singlethread\bin\qmake.exe -v如果 qmake 能输出版本信息说明 Qt 的 WebAssembly 库已经正确安装。这一步验证很重要因为后续 Qt Creator 的 Kit 配置中需要把这个 qmake 路径手动指给 IDE。5. Qt Creator 套件配置与编译验证5.1 配置 WebAssembly 编译套件打开 Qt Creator正常情况下它会自动检测到 Emscripten 工具链和 Qt 的 WebAssembly 版本。你可以在“工具”-“选项”-“Kits”页面看到类似“Qt 6.4.0 WebAssembly”的条目标签。如果没看到不要慌大概率是环境变量没被 Creator 读到手动配置即可。手动配置步骤进入“选项”-“Kits”-“编译器”点击“添加”-“Clang”然后选择 C 编译器为 emsdk 目录下的 em 脚本。以我的安装路径为例C:\QtCode\emsdk\upstream\emscripten\em.bat这里有个细节容易踩坑Qt Creator 识别编译器时需要分别添加 C 编译器和 C 编译器。C 编译器选emcc.batC 编译器选em.bat。如果你只添加了 C 编译器部分 CMake 项目在配置阶段会因找不到 C 编译器而报错。接着在“Kits”页面点击“添加”新建一个编译套件。套件名称随意比如“Qt 6.4.0 WebAssembly”然后在“编译器”下拉框中选择刚添加的 emcc/em“Qt version”下拉框中选择 wasm_singlethread 对应的 qmake。保存后这个 Kit 就会出现在项目构建套件列表里。这里再补充一个坑如果你在 Creator 已经打开的情况下才执行了 emsdk 的永久激活命令需要完全退出 Qt Creator 再重新打开它才会重新读取环境变量。只关项目不关 IDE 是不生效的我因为这个白等了十几分钟。5.2 创建并编译第一个 WebAssembly 工程套件配置完成后新建一个工程测试“文件”-“新建项目”选择“Qt Quick Application”模板。项目名称和路径都用纯英文比如D:\QtCode\hello_wasm。在“构建套件选择”页面勾选上一步创建的“Qt 6.4.0 WebAssembly”套件。点击“完成”后先不要急着改代码保持模板自带的窗口和按钮。直接点击左下角的“构建”按钮。第一次编译会比较慢我记得当时等了大约五到八分钟期间终端输出各种编译信息看起来像是卡住了。这其实是正常的因为要把 Qt 的 wasm 库和应用代码一起链接成最终的 wasm 文件链接阶段特别耗时。如果你的杀毒软件在运行这个时间还会更长。编译完成后在构建输出目录下会生成三个关键产物文件名作用hello_wasm.html网页入口文件包含页面结构和加载逻辑hello_wasm.jsJavaScript 胶水代码负责加载 wasm 模块和内存管理hello_wasm.wasm真正的 WebAssembly 字节码包含编译后的 C 代码5.3 本地部署与文件结构编译完成但不代表能直接双击 html 查看效果。WebAssembly 模块的加载依赖 fetch 等浏览器 API而浏览器安全策略禁止在file://协议下执行这类请求。所以你打开hello_wasm.html时会得到一个白屏页面控制台报 net::ERR_FILE_NOT_FOUND。正确的做法是把这三个文件放到一个本地 HTTP 服务器上。最简单的方式是用 Python 自带的服务cd D:\QtCode\build-hello_wasm-... python -m http.server 8000然后在浏览器访问http://localhost:8000/hello_wasm.html。如果看到 Qt Quick 默认窗口说明整条链路已经通了。Qt Creator 本身也带了运行机制直接点击“运行”按钮Creator 会启动一个内置的本地服务器并自动打开浏览器省去手动起服务的步骤。我建议你两种方式都试一遍因为后续真正部署到线上环境时你会需要理解静态服务器的那套逻辑。有几点部署时需要注意静态服务器的 MIME 类型必须包含application/wasm否则浏览器会拒绝加载 wasm 文件如果是多线程版本还需要后端配置Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp这两个响应头否则 SharedArrayBuffer 会被浏览器拦截。这些都是我在实际部署时踩过的坑默认配置下必然踩提前知道能省不少时间。6. 常见问题与排查技巧实录6.1 高频报错速查表整个搭建过程中我收集了一批高频问题整理成下表基本覆盖了新手会遇到的 90% 的情况现象原因解决办法Kit 列表里没有 WebAssembly 选项安装 Qt 时没勾选 WebAssembly 组件重跑 Qt 在线安装器勾选 WebAssembly 后重新安装编译时提示“emcc 不是内部或外部命令”Emscripten 环境变量未生效重新执行 emsdk activate --permanent重启终端和 Qt Creator网页白屏控制台报 ERR_FILE_NOT_FOUND直接用 file:// 打开了 html改用本地 HTTP 服务器访问wasm 加载失败提示不支持的 MIME 类型服务器没配置 application/wasm修改静态服务器配置加 MIME 类型多线程版运行时报 SharedArrayBuffer is not defined缺少跨源隔离响应头配置 COOP/COEP或先用单线程版本首次编译慢到像死机Qt wasm 库链接耗时长耐心等同时把 Qt 目录和 emsdk 目录加入杀软白名单编译报路径不存在或文件找不到项目路径包含中文字符把项目移到纯英文路径重新构建6.2 我踩过的三个坑第一个坑是中文路径问题。我当时图省事把项目放在D:\工作\学习\hello_wasm下emcc 编译时报了一个编码错误报错信息看了半天没看懂。后来把项目移到D:\QtCode\hello_wasm后一切正常。从那次之后我所有涉及交叉编译的项目一律纯英文路径这个习惯帮我避掉了后面很多麻烦。第二个坑是缓存问题。我中途升级过 Qt 的 RC 版本结果浏览器还在加载旧的 qtloader.js 缓存页面上的按钮点击后没有任何响应。排查了半天最后强制刷新浏览器并删除项目 build 目录重新编译才解决。这个问题的隐蔽性在于编译成功、页面也能打开但运行时行为异常非常容易误导排查方向。第三个坑是 Qt Creator 检测不到 emsdk。原因是当时偷懒只在当前终端执行了emsdk_env.bat压根没做永久激活。这种情况下从桌面图标打开的 Qt Creator 读不到 Emscripten 的环境变量编译器列表里自然找不到 emcc。后来我改用emsdk activate --permanent永久写入环境变量并重启了 IDE问题才彻底消失。结合这三个坑我给后来者的一个总结性建议环境搭建阶段不要把时间花在“看起来能用”上而是要做到“任何新终端都能用”。把你的 emsdk 环境变量做成永久生效项目目录全部纯英文构建缓存该清理就清理这三点前置做到位后续的学习效率会高很多。最后再多说一句我的个人体会。Qt for WebAssembly 这套东西真正跑通之后最让人惊喜的是“一套代码双端运行”的体验——同一个 Qt 工程切换到桌面套件编译就是 exe切换到 WebAssembly 套件编译就是网页。从这个环境跑通之后我陆续把一些 Qt 界面里的英文文案接上了 qt 国际化把耗时逻辑的进度反馈用自定义进度条做成了网页可视化效果都超出预期。不过这些都是从今天这个基础环境延伸出来的后续话题留着下一篇笔记接着写吧。