企业官网建设流程全解析

• 数据可视化
• 桌面应用
• 数据分析

PlotJuggler 4 的浏览器版本是一个静态的、启用多线程（Pthreads + SharedArrayBuffer）的 Qt/WebAssembly 应用，其部署方式与普通前端站点有本质区别：它必须运行在启用跨源隔离的 HTTPS（开发期可为 localhost）环境之下，并配合严格的内容协商、缓存与头部契约。本文基于仓库 docs/WASM_DEPLOYMENT.md 与其配套脚本、测试，完整讲解从 CMake 交叉构建、内容寻址打包，到参考服务器与 Playwright 验收测试的全套流程，读完即可在任意支持 Netlify/Cloudflare Pages 头部格式或等价能力的托管平台上正确发布 PlotJuggler 4。

为什么浏览器版 PlotJuggler 不能“随手打开”？

与普通静态网站不同，PlotJuggler 4 的 Wasm 构建依赖 Emscripten 的 Pthreads 运行时与共享内存（SharedArrayBuffer），这两项能力在浏览器中都有硬性前置条件：

• 必须通过 HTTPS 提供服务（开发期 localhost 例外），否则浏览器不会启用isSecureContext所要求的特性；
• 必须启用跨源隔离（Cross-Origin Isolation），即响应携带Cross-Origin-Opener-Policy: same-origin与Cross-Origin-Embedder-Policy: require-corp，否则SharedArrayBuffer不可用；
• 直接从磁盘双击打开index.html、或使用普通的python -m http.server均不构成受支持的多线程运行环境——前者连 HTTP 响应头都无法提供，后者缺失隔离与 MIME 配置。

这一点在部署验收测试 tests/wasm/deployment.spec.js 中有直接印证：测试显式断言页面中crossOriginIsolated为真、isSecureContext为真、typeof SharedArrayBuffer === 'function'，任何一项不满足都会导致多线程应用启动失败。

Qt 官方 Wasm 部署指南与 Emscripten 的 WebAssembly server setup、Pthreads support 文档分别从 HTML/JS loader/Wasm 模块生成、application/wasmMIME 与 COOP/COEP 角度覆盖了相同要求；本文以下内容则以 PlotJuggler 仓库自身的实现为准。

构建与打包：可复现的发布流水线

工具链版本固定

发布工具链的精确版本统一固定在仓库根目录的 versions.env 中，作为 CMake、脚本、Docker 与 CI 的单一事实来源：

PJ_APP_VERSION=4.0.0 PJ_QT_VERSION=6.11.1 PJ_EMSCRIPTEN_VERSION=4.0.7 PJ_WASM_NODE_VERSION=22.22.1

其中 WebAssembly 构建与桌面构建共用PJ_QT_VERSION（Qt 6.11 针对 Emscripten 4.0.7 提供多线程工具链），Node 则负责确定性压缩输出。保持这些版本精确固定，是“相同输入产生字节级一致发布包”的前提。

CMake 交叉构建

release 工作流的本地等价命令如下（先激活 Emscripten SDK 环境）：

source /path/to/emsdk/emsdk_env.sh cmake -S . -B build-wasm -G Ninja \ -DCMAKE_TOOLCHAIN_FILE=/path/to/Qt/<PJ_QT_VERSION>/wasm_multithread/lib/cmake/Qt6/qt.toolchain.cmake \ -DQT_HOST_PATH=/path/to/Qt/<PJ_QT_VERSION>/gcc_64 \ -DCMAKE_BUILD_TYPE=Release \ -DPJ_BUILD_TESTS=OFF -DPJ_BUILD_DEMOS=OFF \ -DPJ_WASM_WITH_SCENE2D=ON -DPJ_WASM_WITH_SCENE3D=OFF cmake --build build-wasm --target pj_app --parallel 4

关键点：

• wasm_multithread工具链：必须使用 Qt 的多线程 Wasm 工具链文件，这是产出含 Pthreads 运行时与共享内存产物的前提；
• -DQT_HOST_PATH：指向同版本桌面 Qt（gcc_64），供交叉编译期使用宿主工具；
• PJ_WASM_WITH_SCENE2D / PJ_WASM_WITH_SCENE3D：Wasm 特性开关。Scene2D 开启、Scene3D 关闭是文档给出的参考组合；这些开关与仓库中 cmake/PjWasmScene2DDependencies.cmake、cmake/PjWasmScene3DDependencies.cmake 等依赖装配脚本联动。若启用 ROS/Protobuf 解析插件，则还需满足 cmake/PjWasmPluginCommon.cmake 对固定官方插件源码目录（PJ_OFFICIAL_PLUGINS_SOURCE_DIR）的要求，否则会在配置期直接 FATAL_ERROR；
• --target pj_app：产出核心应用目标，其构建产物位于build-wasm/pj_app，包含plotjuggler4.html、plotjuggler4.js、plotjuggler4.wasm、qtloader.js与qtlogo.svg。

打包：内容寻址的确定性发布目录

构建完成后，用打包脚本生成部署包：

node scripts/package_wasm.mjs \ --source build-wasm/pj_app \ --output build-wasm/deploy

scripts/package_wasm.mjs 是打包的权威实现，它做了三层防御性校验：

1. 源产物校验（validateSource）：要求plotjuggler4.html及四个必需工件全部存在；正则检测plotjuggler4.js中是否保留 Emscripten 的PThread运行时标识与shared: true共享内存描述符，并对.wasm文件检查 WebAssembly 魔数头（\x00asm）。任何缺失、无效或单线程构建产物都会被拒绝打包；
2. 输出目录安全（validateReplaceableOutput）：为避免手滑写错--output导致误删无关数据，脚本只允许替换三种情况——目录不存在、目录为空、或目录内含format === 'org.plotjuggler.wasm-deployment.v1'的先前 PlotJuggler 发布包；其他非空目录一律拒绝。且目录会在压缩完成后、替换前再次复查，杜绝并发写满造成的误删；
3. 路径约束：源码目录与输出目录必须互不嵌套、不能指向文件系统根目录。

打包后得到如下稳定布局：

build-wasm/deploy/ ├── index.html ├── manifest.json ├── _headers └── assets/sha256-<bundle-id>/ ├── plotjuggler4.js[.br|.gz] ├── plotjuggler4.wasm[.br|.gz] ├── qtloader.js[.br|.gz] └── qtlogo.svg[.br|.gz]

• 入口index.html稳定不变：打包脚本将源码plotjuggler4.html中的src="plotjuggler4.js"等引用改写为内容寻址路径，并注入locateFile回调，使 Wasm 模块也从assets/<bundle-id>/加载（见脚本中replaceExactlyOnce与qtLoad标记改写逻辑）；
• bundle-id是内容寻址的：由四个运行时工件各自的文件名、字节数、SHA-256 摘要串联后再次取 SHA-256 的前 32 位十六进制组成（sha256-<32 hex>）。任一运行时工件变化，目录名随之改变，旧 URL 自然失效；
• 压缩变体：.js、.wasm、.svg、.html属于可压缩类型，字节数不低于 1024 的工件会生成.br与.gz两个变体；Brotli 固定使用 quality 9、窗口 22（脚本注释说明 quality 11 在参考主机上耗时超过五分钟仍无法完成，quality 9 是发布侧的成本权衡），Gzip 固定 level 9 且将 mtime 归零、OS 字节置为 255（RFC 1952 的“unknown”），以消除不同平台 Node 运行时的字节差异。

manifest.json：发布包的“契约清单”

scripts/package_wasm.mjs 生成的 manifest.json（运行时产物）逐文件记录：

• 每个逻辑文件（identity/Brotli/gzip 三种表示）的路径、字节大小、SHA-256、MIME 类型、缓存类别（revalidate或immutable）；
• 压缩运行时与参数（Node 版本、zlib 版本、Brotli quality/window、Gzip level/mtime/OS）；
• 必需的响应头集合（COOP/COEP/CORP/nosniff）与两类缓存策略字符串；
• _headers文件自身的路径、字节数、SHA-256，作为“部署配置”独立纳入清单。

正因为 Node 版本被 release CI 固定（PJ_WASM_NODE_VERSION）、压缩参数全部写死、gzip 元数据归一化，相同输入必然产出字节级一致的发布包，这为发布审计与复现提供了坚实基础。

生成的 _headers 文件

打包脚本同时生成_headers文件（其内容由deploymentHeaders()函数产出），面向支持 Netlify/Cloudflare Pages_headers格式的托管平台：

/* Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Resource-Policy: same-origin X-Content-Type-Options: nosniff / Cache-Control: no-cache /index.html Cache-Control: no-cache /manifest.json Cache-Control: no-cache /assets/sha256-<bundle-id>/* Cache-Control: public, max-age=31536000, immutable

需要注意：_headers只负责配置头部，它并不会让托管平台自动在.br/.gz与 identity 之间做预压缩变体选择——预压缩变体的启用仍需在托管平台侧显式开启。

必需 HTTP 契约：浏览器侧生命线

隔离与安全头部

每一个响应——包括入口页与运行时资源——都必须携带以下四个头部：

same-origin的 COOP/COEP 组合把窗口变成可与自身共享内存的隔离上下文（启用 Pthreads 的SharedArrayBuffer），CORP: same-origin防止其他源嵌入资源，nosniff阻止 MIME 嗅探。参考服务器 scripts/serve_wasm.mjs 与测试 tests/wasm/deployment.spec.js 均以这四个值作为硬性断言。

内容协商：三态编码选择

对每个逻辑资源 URL，应按以下优先级响应：

1. 当Accept-Encoding允许br时，优先返回其.br兄弟文件，并携带Content-Encoding: br；
2. 否则若允许gzip，返回.gz并携带Content-Encoding: gzip；
3. 否则返回 identity 原文件（不设Content-Encoding）。

同时始终保持逻辑资源的 MIME 类型——尤其是plotjuggler4.wasm必须返回Content-Type: application/wasm，这是浏览器启用流式编译（streaming compilation）的前提；凡存在编码变体的资源必须返回Vary: Accept-Encoding，否则共享缓存在不同客户端之间会串味。

参考服务器 scripts/serve_wasm.mjs 完整实现了这一协商：它解析Accept-Encoding的 q 值（含*通配与identity;q=0的显式禁用），在 br/gzip/identity 之间按“q 值优先、br > gzip > identity 次序兜底”选择表示，并以所选表示的 SHA-256 生成强ETag（"sha256-..."）支持If-None-Match条件请求返回 304。它还会拒绝未在 manifest 中声明的文件（返回 404、Cache-Control: no-store），避免把部署包之外的杂散文件暴露出去。

缓存策略：入口可换新、资产不可变

• 稳定的index.html与manifest.json使用Cache-Control: no-cache，客户端每次都会向服务器重新校验，以便获取新 bundle 的入口；
• assets/sha256-<bundle-id>/之下的所有文件使用Cache-Control: public, max-age=31536000, immutable，因为其 URL 随任何运行时资产的变更而整体变化，可安全长缓存一年。

若托管平台不支持预压缩变体，也可以忽略.br/.gz兄弟文件、改用平台自身的等效动态压缩，前提是保持相同的 MIME、隔离与缓存契约不变。

跨源数据与全局策略

应用运行时加载的跨源数据（如远程数据集、ROS/Protobuf 流）有自己独立的 CORS/CORP 要求。文档明确提醒：不要为了迁就某个无关的远端服务器而全局弱化应用资产的隔离策略——跨源数据应在其数据源上显式配置 CORS/CORP，应用资产的四头部契约必须原样保留。

浏览器本地状态：什么能持久、什么绝不能持久

Wasm 版的浏览器本地状态模型在 pj_app/src/BrowserPersistence.h 中有权威定义（其实现见 pj_app/src/BrowserPersistence.cpp）：

• 上传的文件被暂存在页面级临时文件系统，获得不透明的浏览器身份标识，刷新页面即丢失，不会持久化；
• 普通的QSettings调用者在 Wasm 下被重定向到页面生命周期存储（Wasm 默认后端指向/tmp），所有既有调用方在“当前页面”范围内仍然可用，但不会意外地让路径、插件配置、凭据等内容变得长期持久；
• 唯一真正跨刷新持久的浏览器状态只有两类，且都由BrowserPersistence拥有：
  1. 经过类型化校验的偏好 allowlist（durablePreferenceKeys()/sanitizePreference()：只有显式列入 schema 的键、且值通过类型校验，才允许写入持久层）；
  2. 一个有限的、无数据源绑定的通用布局 recipe 列表（recentLayouts()/rememberGenericLayout()，且isSafeGenericLayoutRecipe()对 XML 做安全校验）。

与此相对，路径、上传身份、插件配置与凭据被有意排除在浏览器本地持久化之外。另外，带数据源绑定的布局在回放时下载的是“逻辑引用”，需要用户在重放时显式重新选择对应文件，而不是自动恢复路径。

本地服务与发布验收：用参考服务器验证一切

参考服务器

仓库提供了 manifest 驱动的本地参考服务器：

node scripts/serve_wasm.mjs --root build-wasm/deploy --port 6931

scripts/serve_wasm.mjs 的实现要点：

• 默认绑定127.0.0.1（--host可改，--port 0可选临时端口）；
• 启动时强制校验 manifest 的格式、入口、必需头部集合、缓存策略以及_headers文件与 manifest 记录的字节数/SHA-256 一致性，任何偏差都会拒绝启动；
• 只服务 manifest 声明过的文件；执行真实的 Brotli/gzip 内容协商；返回生产级头部与缓存契约；支持条件请求（304）与 HEAD；
• 它定位为正确性参考与开发服务器，不是托管 TLS 或高可用的生产服务。

Playwright 部署验收测试

仓库以 Playwright 对打包产物做端到端验收，命令如下：

cd tests/wasm npm ci npx playwright install chromium PJ_WASM_PACKAGE_DIR="$PWD/../../build-wasm/deploy" npm run test:deployment

其中test:deployment由 tests/wasm/package.json 映射到 tests/wasm/deployment.playwright.config.js（单 worker、180 秒超时、失败截图），执行 tests/wasm/deployment.spec.js 中的两组测试：

1. 协议级校验：直接以原始 HTTP 请求断言 manifest 格式与打包运行时参数；_headers的字节数与哈希；入口页在Accept-Encoding: identity下的text/html、no-cache与注入的内容寻址src；对 Wasm 资源分别以br, identity;q=0、gzip, identity;q=0、identity请求，逐一核对Content-Type: application/wasm、Content-Encoding、Cache-Control: public, max-age=31536000, immutable、Vary: Accept-Encoding、ETag、响应字节数与 SHA-256 与 manifest 完全一致；If-None-Match返回 304；未声明文件与_headers本身均返回 404；
2. 冷启动浏览器验收：用全新的 Chromium 从打包根目录启动，等待 Qt 应用就绪（#screen可见、无Application exit错误、控制台出现Scanning 0 plugin folder(s)），并断言crossOriginIsolated、isSecureContext、SharedArrayBuffer三者全部可用，plotjuggler4.wasm实际以br编码、immutable 缓存被加载，且全程无页面异常。

这组测试把“原始编码字节哈希、MIME、缓存/隔离头部、条件请求、多线程冷启动”全部固化成了可重复的发布门槛，任何破坏 HTTP 契约或打包正确性的改动都会在此被拦截。

部署到托管平台的核对清单

综合上述契约，将发布包部署到任何托管平台前应逐项核对：

1. 上传build-wasm/deploy目录的全部内容（含_headers与assets/sha256-<bundle-id>/下的全部编码变体）；
2. 确认平台应用了四头部契约（Netlify/Cloudflare Pages 可通过_headers，其他平台请在平台配置或边缘函数中显式添加）；
3. 确认平台对.br/.gz预压缩变体启用内容协商（或接受动态压缩并保持 MIME/缓存/隔离契约不变）；
4. 确认.wasm响应为application/wasm且带Vary: Accept-Encoding；
5. 入口与manifest.json走no-cache，assets/走public, max-age=31536000, immutable；
6. 上线前用node scripts/serve_wasm.mjs本地跑通参考服务器，再执行上述 Playwright 部署验收测试；
7. 跨源数据源单独配置 CORS/CORP，绝不为此全局弱化应用资产策略。

完成以上步骤，PlotJuggler 4 的多线程 Wasm 构建即可在浏览器中稳定运行，并获得与桌面端一致的交互体验。

• 数据可视化
• 桌面应用
• 数据分析