深入解析 Rerun Web Viewer 构建工具 build_web_viewer从 Wasm 编译到 JS 绑定生成【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本指南以crates/build/re_dev_tools/src/build_web_viewer/为核心系统讲解 Rerun 项目如何将re_viewerRust 编写的三维/多模态数据可视化器编译为 WebAssemblyWasm、生成对应的 JavaScript 绑定并把产物放置到re_web_viewer_server的静态资源目录中最终让浏览器通过 Web 方式运行 Rerun Viewer。读完本文你将掌握build-web-viewer子命令的完整用法--release、--debug、-g、--target、--out、--features等全部参数理解其三步流水线cargo 编译 → wasm-bindgen 绑定生成 → wasm-opt 优化的底层实现并了解它如何在re_web_viewer_server的build.rs中被自动调用从而在本地构建、发布 Python 包、打包 JS SDK 等场景中正确使用这一工具链。一、工具定位既是二进制也是库build_web_viewer模块是 Rerun 构建工具集合re_dev_tools中的一个子命令它在项目中的定位正如 README.md 所言Binary and library for building the Rerun web viewer.它同时以两种形态存在二进制Binary通过pixi run dev-tools -- build-web-viewer在命令行直接调用库Library其核心逻辑被re_web_viewer_server的build.rs在 Rust 构建脚本中复用实现编译re_web_viewer_server时自动顺带构建 Web Viewer的效果。从源码结构看模块由两个文件组成lib.rs核心构建逻辑约 260 行与 mod.rsargh 命令行参数定义与入口main。re_dev_tools的 main.rs 将BuildWebViewer注册为顶层三大子命令之一另外两个是BuildExamples与SearchIndex因此通过pixi run dev-tools --help可以查看全部可用工具。二、快速上手两条核心命令README 给出了两条可直接运行的命令分别对应调试构建与发布构建# 调试构建快速迭代产物小、编译快不经过 wasm-opt 优化 pixi run dev-tools -- build-web-viewer # 发布构建release 编译 wasm-opt 优化-g 表示保留调试符号 pixi run dev-tools -- build-web-viewer --release -g第一条等价于cargo run --locked -p re_dev_tools -- build-web-viewer参见 pixi.toml 中dev-tools任务的定义默认以Debug模式构建第二条以WebRelease模式构建并额外执行wasm-opt优化-g表示即使在 release 构建中也保留调试符号换取更好的 panic 调用栈与浏览器内性能剖析能力详见下文调试符号小节。更贴近日常的封装命令仓库在 pixi.toml 中还预置了面向日常开发与发布的封装命令它们内部正是调用build-web-viewer# 编译 web-viewer 的 wasmdebug不含 CLI pixi run rerun-build-web # 编译 web-viewer 的 wasm 并同时构建 rerun-cli pixi run rerun-build-web-cli # 以 release 模式编译 web-viewer 的 wasm pixi run rerun-build-web-release其中rerun-build-web的实际命令为cargo run -p re_dev_tools -- build-web-viewer --no-default-features --features analytics,map_view --debug可见它在 debug 模式下显式关闭默认特性、只启用analytics与map_view两个特性默认特性只含analytics见 mod.rs 中default_features()的返回值这能显著缩短迭代编译时间。三、命令行参数全解析build-web-viewer使用argh进行参数解析完整参数定义见 mod.rs。下表汇总了全部参数参数短选项类型默认值说明--release—开关关以 release 编译并运行wasm-opt与--debug互斥--debug—开关关以 debug 编译且不运行wasm-opt与--release互斥--debug-symbols-g开关关即使在 release 构建中也保留调试符号改善 panic 调用栈、支持浏览器内剖析--target-t选项browser目标形态browser、module或no-modules-base--out-o选项见下输出目录相对 workspace 根目录的路径--features-F选项analytics透传给re_viewer的特性列表逗号分隔--no-default-features—开关关排除re_viewer的默认特性--timings—开关关生成 cargo 构建耗时报告位于target-dir/cargo-timings/几点关键细节--release与--debug必须二选一。入口main中校验逻辑为--release且非--debug→WebRelease--debug且非--release→Debug否则直接报错Exactly one of --release or --debug must be set。默认输出目录。不传-o时产物会放到crates/top/re_web_viewer_server/web_viewer/由default_build_dir()计算得出见 lib.rs。该目录下已预置index.html、favicon.ico、manifest.json、sw.js等 Web 应用外壳文件构建工具只负责填充re_viewer.js与re_viewer_bg.wasm这两个核心产物。目录中的 README.md 也印证了这一点You can build the web viewer with:pixi run rerun-build-web-release。三种 Target 的差异定义于 lib.rsbrowser默认no_modules(true)且typescript(false)生成无模块、可直接被script标签加载的绑定moduleno_modules(false)且typescript(true)生成 ES Module 形态并附带.d.ts类型声明no-modules-baseno_modules(true)且typescript(true)是专为rerun_js内后处理定制的目标。四、三步流水线核心构建原理build()函数lib.rs按顺序执行三个阶段。理解每一步你就掌握了 Rerun Web 端构建的全部机制。第一步cargo 编译 Rust → Wasm工具首先将当前目录切换到 workspace 根目录然后以re_viewer为目标 crate执行等价于以下命令的编译cargo build \ --packagere_viewer \ --lib \ --targetwasm32-unknown-unknown \ --target-dirworkspace/target/wasm关键实现细节独立的 target 目录产物放到target/wasm而非默认 target 目录这是为了支持递归 cargo 构建——因为build_web_viewer可能从另一个build.rs中被触发如re_web_viewer_server嵌套在target内部可保证cargo clean一并清理。profile 区分Debug 模式不加 profile 参数WebRelease模式追加--profileweb-release对应 Cargo.toml 中定义的 profile。强制指定项目配置命令追加--config.cargo/config.toml确保 wasm 编译使用仓库自带的 target 配置。在 .cargo/config.toml 的[target.wasm32-unknown-unknown]段中为 wasm32 目标设置了--cfggetrandom_backendwasm_js以及-Ctarget-featuresimd128,bulk-memory,nontrapping-fptoint,multivalue即启用 SIMD 自动向量化及多项 Wasm 提案特性。清空 RUSTFLAGS源码注释明确说明当从 build script 中调用时绝不能让预编码的RUSTFLAGS/CARGO_ENCODED_RUSTFLAGS泄漏进子进程——这些由 Cargo 加载$CARGO_HOME/config.toml生成的标志只对原生目标有效对 wasm 构建毫无意义因此通过cmd.env_remove(RUSTFLAGS)与cmd.env_remove(CARGO_ENCODED_RUSTFLAGS)显式移除。前置清理构建前会删除build_dir中旧的re_viewer_bg.wasm与re_viewer.js避免残留产物混淆。编译完成的标准输出形态为re_viewer.wasm位于target/wasm/wasm32-unknown-unknown/profile/re_viewer.wasm。第二步wasm-bindgen 生成 JS 绑定随后工具调用wasm_bindgen_cli_support::Bindgenwasm-bindgen-cli-supportcrate已在 re_dev_tools/Cargo.toml 中声明依赖将 Wasm 与 JS 胶水代码绑定输入上一步产出的re_viewer.wasm输出文件名为re_viewer.js与re_viewer_bg.wasm输出目录即最终build_dir默认web_viewer/按上文--target的选择决定no_modules与typescript的组合。这里有一个非常实用的排障提示内嵌在源码中如果绑定失败且报错信息以cannot import from modules (env)开头典型场景是某个依赖调用了std::time::Instant::now()之类无法在无模块环境使用的 API工具会给出诊断命令建议wasm2wat target/wasm/wasm32-unknown-unknown/web-release/re_viewer.wasm | rg env wasm2wat target/wasm/wasm32-unknown-unknown/web-release/re_viewer.wasm | rg call .now\b -B 20即用wasm2wat将 Wasm 反汇编为 WAT 文本检索env导入与now调用定位到底是谁引入了宿主环境依赖。第三步仅 releasewasm-opt 优化仅当profile WebRelease时执行。工具调用 binaryen 提供的wasm-opt通过apt/brew/dnf安装binaryen获得pixi 环境中也已锁定binaryen 117.*见 pixi.toml命令形态为wasm-opt re_viewer_bg.wasm -O2 --output re_viewer_bg.wasm \ --enable-reference-types \ --enable-simd --enable-bulk-memory \ --enable-nontrapping-float-to-int --enable-multivalue \ --vacuum [ -g | --strip-debug ]优化要点-O2是常规的尺寸/性能平衡优化级别显式开启的--enable-simd、--enable-bulk-memory、--enable-nontrapping-float-to-int、--enable-multivalue与第一步编译时使用的-Ctarget-feature完全对应。源码注释解释了兼容性策略JS 加载器在加载.wasm前会做 SIMD 特性检测而其余特性在 Chrome/Firefox/Safari 中都比 SIMD 更早得到支持因此 SIMD 检测即可覆盖全部特性--vacuum执行死代码消除调试符号处理-g时保留调试符号否则--strip-debug剥离以进一步缩小体积。这正是文档示例--release -g的含义——发布版也保留符号便于线上崩溃定位与性能剖析。优化完成后最终产物落定build_dir/re_viewer_bg.wasm与build_dir/re_viewer.js控制台打印Finished wasm_path表示构建成功。五、与 re_web_viewer_server 的集成build.rs 自动调用README 特别指出 This is also called by thebuild.rsofre_web_viewer_server.。这句话背后有一套完整的构建时策略实现在 re_web_viewer_server/build.rs 中构建脚本根据三个环境变量 / feature 决定是否需要 wasmRERUN_DISABLE_WEB_VIEWER_SERVER或__disable_server完全禁用 Web Viewer 服务RERUN_TRAILING_WEB_VIEWER或__trailing_web_viewerwasm 将在后处理阶段追加进二进制构建期不需要RERUN_EXTERNAL_WEB_VIEWER或__external_web_viewerwasm 运行时从磁盘上的 zip 归档例如 Python wheel 内附带的加载。若三者均未启用needs_wasm true则断言./web_viewer/re_viewer.js与./web_viewer/re_viewer_bg.wasm必须存在否则编译失败并提示Web viewer not found, run pixi run rerun-build-web to build it!也就是说先运行build-web-viewer或rerun-build-web生成 Wasm 产物之后任何依赖re_web_viewer_server的构建才能通过。这条错误信息是开发者最常见的坑而它指向的解决命令正是本 README 的核心命令。六、产物去向与使用场景构建完成的re_viewer.jsre_viewer_bg.wasm落在crates/top/re_web_viewer_server/web_viewer/默认与项目预置的index.html、sw.jsService Worker、manifest.jsonPWA 清单、favicon.ico等文件共同组成一个完整的 Web 应用。re_web_viewer_server通过内置 HTTP 服务把整个目录作为静态站点对外提供从而在浏览器中打开 Rerun 可视化界面。除了re_web_viewer_server构建产物还会流向其他渠道Python 包rerun_py的py-build-web-viewer/py-build-web-viewer-release任务pixi.toml在发布流程中依赖已构建的 wasm将其随 wheel 一并分发JS SDKrerun_js的构建脚本消费no-modules-base目标产物在其基础上做进一步后处理生成web-viewernpm 包相关流水线可见 rerun_js/scripts/common.mjs 等脚本。七、常见问题速查现象原因解决办法Web viewer not found, run pixi run rerun-build-webre_web_viewer_server构建期未找到 wasm 产物先执行pixi run rerun-build-webdebug或pixi run rerun-build-web-release发布Exactly one of --release or --debug must be set未指定或同时指定了构建模式必须且只能二选一Failed to run wasm-opt, it may not be installed系统缺少 binaryenapt/brew/dnf安装binaryen或使用 pixi 环境已锁定 binaryen 117.*wasm-bindgen 报cannot import from modules (env)依赖链引入了宿主环境 API如Instant::now()用wasm2wat ... | rg env定位问题依赖八、总结build_web_viewer是 Rerun Web 端构建链路的枢纽它以build-web-viewer子命令对外暴露内部通过cargo 编译 Wasm → wasm-bindgen 生成 JS 绑定 →release 时wasm-opt 优化三步流水线将 Rust 编写的re_viewer变成浏览器可运行的re_viewer.jsre_viewer_bg.wasm并直接送入re_web_viewer_server/web_viewer/目录。理解它的参数语义、默认输出位置、profile 与 target 差异以及它与build.rs的联动关系是本地调试、打包发布 Rerun Web Viewer 的第一步。需要深入源码的读者可以继续阅读 lib.rs、mod.rs 以及 re_web_viewer_server/build.rs 三个文件它们完整呈现了本工具的全部实现细节。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考