Substrate wasm-builder 完全指南：将 Runtime 编译为 Wasm 二进制并集成进 cargo 构建流程

区块链开发框架后端【免费下载链接】substrateSubstrate: The platform for blockchain innovators项目地址https://gitcode.com/gh_mirrors/su/substrate点击查看免费下载导读在 Substrate 生态中Runtime 需要同时以原生native代码和 WebAssemblyWasm两种形式交付链上执行与状态验证依赖 Wasm 版本的 Runtime。substrate-wasm-builder正是解决这一痛点的构建工具——它把将项目编译为 Wasm 二进制这一过程无缝集成进主cargo build流程让开发者无需手动切换目标平台即可自动产出WASM_BINARY常量。本文基于 utils/wasm-builder/README.md 及该 crate 的完整源码系统讲解其项目配置步骤、WasmBuilder链式 API、Feature 透传机制、全部环境变量以及工具链前置条件并结合仓库内的真实 Runtime 项目如 bin/node/runtime/build.rs给出可直接复用的实战方案。一、wasm-builder 是什么把 Wasm 构建内嵌进 cargosubstrate-wasm-buildercrate 名为substrate-wasm-builder版本5.0.0-dev见 utils/wasm-builder/Cargo.toml是一个构建工具库其核心定位是将你的项目编译为 Wasm 二进制这一过程集成到主cargo构建流程中。它通过标准的 Cargo build scriptbuild.rs机制工作当宿主项目执行cargo build时Cargo 会先运行build.rswasm-builder 在此阶段完成以下工作对应 utils/wasm-builder/src/builder.rs 中的build_project函数检查工具链前置条件Rust 版本、wasm32-unknown-unknowntarget、rust-lld链接器在target目录下临时生成一个独立的 Wasm 工程wbuild工作区并复制主工程Cargo.lock以保证依赖版本一致以cargo rustc --targetwasm32-unknown-unknown编译出原始 Wasm 二进制对产物做 compact基于wasm-opt裁剪、去调试段与 compress基于 zstd 压缩处理校验 Wasm 中是否包含runtime_version自定义段该段由sp_version::runtime_version属性宏生成在OUT_DIR下生成wasm_binary.rs默认文件名供宿主项目通过include!引入。最终产物形态、生成逻辑以及 rerun-if-changed 指令都在 utils/wasm-builder/src/wasm_project.rs 中实现下文各节将逐一展开。二、项目配置三步让 Runtime 具备 Wasm 构建能力原文档明确指出一个需要被编译为 Wasm 二进制的项目必须满足两个条件并额外执行一步引入操作。2.1 在build-dependencies中声明 wasm-builder在项目典型场景是 Runtime crate的Cargo.toml中添加依赖[build-dependencies] substrate-wasm-builder { version 5.0.0-dev, path ../../utils/wasm-builder, optional true }注意两点该依赖声明为optional并且只在启用stdfeature 时才真正生效见 2.2 的#[cfg(feature std)]包裹。这样在纯no_std的 Wasm 编译路径中不会递归触发 wasm-builder 自身。仓库内的真实范例即如此参见 bin/node/runtime/Cargo.toml其build-dependencies中substrate-wasm-builder { version 5.0.0-dev, path ../../../utils/wasm-builder, optional true }并且default [std]。2.2 编写build.rs项目的build.rs需要包含如下代码与原文档一致且与仓库 bin/node/runtime/build.rs 中的实现完全对应fn main() { #[cfg(feature std)] { substrate_wasm_builder::WasmBuilder::new() // Tell the builder to build the project (crate) this build.rs is part of. .with_current_project() // Make sure to export the heap_base global, this is required by Substrate .export_heap_base() // Build the Wasm file so that it imports the memory (need to be provided by at instantiation) .import_memory() // Build it. .build(); } }2.3 通过include!引入生成的常量最后一步在项目的 lib 源码通常是src/lib.rs中添加include!(concat!(env!(OUT_DIR), /wasm_binary.rs));wasm_binary.rs由 wasm-builder 在OUT_DIR中生成内容形如对应 utils/wasm-builder/src/builder.rs 的写入逻辑pub const WASM_BINARY: Option[u8] Some(include_bytes!(...compact.compressed.wasm)); pub const WASM_BINARY_BLOATY: Option[u8] Some(include_bytes!(...wasm));其中WASM_BINARY经过 compact 与 compress 处理后的精简 Wasm 二进制是链上部署、原生执行通过sc-executor加载实际使用的版本WASM_BINARY_BLOATY编译器直接产出的原始未裁剪Wasm 二进制体积更大主要用于调试与测试场景两者的类型均为Optionstatic [u8]——即当构建被跳过且首次构建不存在 Wasm 产物时值为None见 utils/wasm-builder/src/builder.rs 中provide_dummy_wasm_binary_if_not_exist写入的None常量。三、WasmBuilder 链式 API 详解WasmBuilder的设计采用了类型安全的分阶段构造见 utils/wasm-builder/src/builder.rsWasmBuilder::new()返回WasmBuilderSelectProject必须先选择目标项目再进入WasmBuilder阶段配置并调用build()。原文档重点展示了最常用的with_current_project/export_heap_base/import_memory三个方法结合源码可完整梳理出全部可用方法。3.1 选择构建目标项目方法签名与行为说明with_current_project()无参返回WasmBuilder构建当前 crate。底层通过CARGO_MANIFEST_DIR环境变量定位Cargo.toml该变量由 Cargo 在运行build.rs时始终注入utils/wasm-builder/src/builder.rswith_project(path)传入路径返回ResultWasmBuilder, static str构建指定项目。路径必须指向一个真实存在的Cargo.toml否则返回错误Project path must point to the Cargo.toml of the projectutils/wasm-builder/src/builder.rs。可用于在某个 crate 的build.rs中构建工作区里的其他 Runtime3.2 配置构建行为方法作用源码实现细节export_heap_base()导出__heap_base全局变量向RUSTFLAGS追加-Clink-arg--export__heap_base。该全局变量是 Wasm Runtime 的线性内存堆起点Substrate 加载 Wasm 后需要据此初始化堆utils/wasm-builder/src/builder.rsimport_memory()让 Wasm 二进制导入而非内部定义线性内存追加-C link-arg--import-memory。这样内存由宿主在实例化时提供是 Substrate 执行 Wasm Runtime 的标准做法utils/wasm-builder/src/builder.rsset_file_name(name)自定义OUT_DIR下生成的文件名默认值为wasm_binary.rs即include!(concat!(env!(OUT_DIR), /wasm_binary.rs))中的文件名utils/wasm-builder/src/builder.rsappend_to_rust_flags(flag)追加任意合法的RUSTFLAGS片段原样追加需要自行保证合法性utils/wasm-builder/src/builder.rsenable_feature(feature)为 Wasm 构建显式启用某个 Cargo feature该 feature 必须是项目Cargo.toml中定义过的utils/wasm-builder/src/builder.rsdisable_runtime_version_section_check()关闭runtime_versionWasm 段的校验默认会强制检查该段存在见 6.3测试等场景可关闭utils/wasm-builder/src/builder.rs3.3 触发构建build()build()是整个流程的入口utils/wasm-builder/src/builder.rs其执行顺序为读取OUT_DIR并计算目标输出文件路径调用check_skip_build()判断是否命中SKIP_WASM_BUILD或SKIP_CRATE_WASM_BUILD环境变量见 5.2若跳过仍会输出rerun-if-changed指令并在产物不存在时写入None版本的占位常量否则调用build_project(...)执行真实构建最后生成rerun-if-changed指令保证SKIP_WASM_BUILD、FORCE_WASM_BUILD、SKIP_CRATE_WASM_BUILD等环境变量变化时 Cargo 会重新执行build.rs见 utils/wasm-builder/src/builder.rs。四、Wasm 构建的内部流水线理解内部流水线有助于排查构建问题。核心逻辑位于 utils/wasm-builder/src/wasm_project.rs 的create_and_compile函数分为四个阶段。4.1 生成临时 Wasm 工程wasm-builder 会在target目录下寻找wbuild工作区get_wasm_workspace_root向上回溯OUT_DIR直至遇到build目录见 utils/wasm-builder/src/wasm_project.rs并生成一个Cargo.toml定义cdylib类型的库 crate名为crate-wasm引用原项目作为依赖并设置default-features false与显式 feature 列表同时注入[profile.release]panic abort、lto thin、[profile.production]继承 release 并设置lto fat、codegen-units 1、[profile.dev]panic abort三套 profile并继承主工作区的[patch]段utils/wasm-builder/src/wasm_project.rs一个src/lib.rs内容为#![no_std] pub use wasm_project::*;从主工程复制的Cargo.lock确保依赖版本锁定与主构建一致utils/wasm-builder/src/wasm_project.rs。4.2 编译 Wasm 二进制通过cargo rustc --targetwasm32-unknown-unknown编译并注入固定RUSTFLAGSutils/wasm-builder/src/wasm_project.rs-C target-cpumvp -C target-feature-sign-ext -C link-arg--export-table 自定义 flags WASM_BUILD_RUSTFLAGS其中-C target-cpumvp与-C target-feature-sign-ext保证 Wasm 产物兼容最广泛的执行环境MVP 指令集-C link-arg--export-table导出函数表供宿主通过表索引调用 Runtime 导出函数编译时会移除CARGO_TARGET_DIR防止 cargo 对 target 目录加锁导致死锁与CARGO_ENCODED_RUSTFLAGS防止宿主的 flags 干扰 Wasm 构建并设置SKIP_WASM_BUILD防止递归调用 wasm-builder 自身。4.3 compact 与 compress依据选中的 profileRelease/Production会执行Debug不执行见Profile::wants_compactutils/wasm-builder/src/wasm_project.rscompact使用wasm-optOptimizationOptions::new_opt_level_0()mvp_features_only()StripDwarf去调试信息段生成name.compact.wasmcompress使用sp-maybe-compressed-blobprimitives/maybe-compressed-blob按CODE_BLOB_BOMB_LIMIT上限做 zstd 压缩生成name.compact.compressed.wasm若超限则退回未压缩版本并发出警告utils/wasm-builder/src/wasm_project.rs。最终WASM_BINARY优先指向压缩产物wasm_binary_compressed.or(wasm_binary)。4.4 mtime 调整与重编译触发adjust_mtime会把 bloaty 与 compact/compressed 产物的修改时间对齐到OUT_DIR/../invoked.timestamp避免因产物时间戳晚于build.rs执行时间戳而导致 Cargo 每次都重新执行build.rsutils/wasm-builder/src/wasm_project.rs。同时generate_rerun_if_changed_instructions会递归追踪所有依赖包的*.rs/*.toml文件及Cargo.lock任一变更即触发重构建utils/wasm-builder/src/wasm_project.rs。五、环境变量配置全表原文档给出了 8 个环境变量结合源码还可补充WASM_BUILD_WORKSPACE_HINT与WASM_BUILD_TYPE支持的production取值。所有变量均在 utils/wasm-builder/src/lib.rs 中定义。环境变量作用补充说明SKIP_WASM_BUILD跳过所有 Wasm 构建仅重编译原生代码若首次构建且不存在 Wasm 产物WASM_BINARY与WASM_BINARY_BLOATY会被置为None见 2.3 的占位逻辑SKIP_PROJECT_NAME_WASM_BUILD跳过单个项目的 Wasm 构建PROJECT_NAME为 crate 名大写并把-替换为_如node-runtime对应NODE_RUNTIME。由generate_crate_skip_build_env_name生成utils/wasm-builder/src/builder.rsWASM_BUILD_TYPE设置 Wasm 构建类型原文档给出release/debug源码中完整支持三种 profiledebug、release、production分别对应--profile dev/release/production。默认等于主构建类型例外主构建为 debug 时 Wasm 默认仍用 releasedebug 太慢仅当显式设置该变量时才采用 debugProfile::detectutils/wasm-builder/src/wasm_project.rsFORCE_WASM_BUILD强制触发一次 Wasm 构建后续调用需改变变量值才再次生效。由于 wasm-builder 已向 cargo 注册文件与变量监听一般场景无需使用WASM_BUILD_RUSTFLAGS扩展传给 Wasm 构建的RUSTFLAGS追加在固定 flags 之后utils/wasm-builder/src/wasm_project.rsWASM_BUILD_NO_COLOR禁用 Wasm 构建的彩色输出设置后--coloralways不再追加提示信息也不做颜色渲染color_output_enabledutils/wasm-builder/src/lib.rsWASM_TARGET_DIRECTORY将构建出的 Wasm 二进制复制到指定目录路径必须为绝对路径否则构建会报错退出按crate_name.wasm命名复制utils/wasm-builder/src/wasm_project.rs。常用于 CI 产物收集WASM_BUILD_TOOLCHAIN指定编译 Wasm 所用的工具链格式与 cargo/rustup 一致如nightly-2020-02-20会以rustup run toolchain cargo调用utils/wasm-builder/src/lib.rsWASM_BUILD_WORKSPACE_HINT提示工作区根目录源码新增README 未列wasm-builder 默认从OUT_DIR向上查找Cargo.lock以定位工作区若改了 target 目录导致找不到可通过该变量指向真实工作区utils/wasm-builder/src/wasm_project.rsCARGO_NET_OFFLINE值为true时所有子进程加--offline适用于无网络/离线 CI 环境避免构建过程发起网络请求5.1 关于 cargo 命令的选择算法当未通过WASM_BUILD_TOOLCHAIN指定工具链时get_cargo_commandutils/wasm-builder/src/lib.rs会按以下优先级挑选支持 Substrate Wasm 环境的 cargo当前CARGO环境变量指向的 cargo若版本 1.68 或是 nightly或设置了RUSTC_BOOTSTRAP系统默认cargo同样要求满足上述条件通过rustup toolchain list枚举所有已安装工具链选出最新的可用版本——且稳定版总是优先于 nightly即使 nightly 更新get_rustup_commandutils/wasm-builder/src/lib.rs。supports_substrate_wasm_env的判断逻辑utils/wasm-builder/src/lib.rs设置RUSTC_BOOTSTRAP视为 nightly否则要求cargo --version解析出的版本满足major 1 || (major 1 minor 68) || is_nightly。版本解析与比较实现在 utils/wasm-builder/src/version.rs含排序规则stable nightly再按 major/minor/patch/日期比较。六、前置条件与常见问题排查6.1 工具链要求原文档明确了两个可选项rust nightly wasm32-unknown-unknowntargetrust stable 且版本至少 1.68.0 wasm32-unknown-unknowntarget。使用rustup安装特定工具链时务必同步安装对应的 wasm target例如rustup install nightly-2020-02-20 rustup target add wasm32-unknown-unknown --toolchain nightly-2020-02-20前置检查实现在 utils/wasm-builder/src/prerequisites.rs 的check中先校验 Rust 版本再在临时目录生成一个最小的cdylib工程执行cargo build --targetwasm32-unknown-unknown以验证 wasm target 可用并顺带通过rustc --version捕获 rustc 版本用于构建日志。若检查失败会打印红色错误信息并以退出码 1 终止构建。6.2 常见错误rust-lldnot found在 Wasm 链接阶段若使用较新的 Rust 工具链但缺少链接器会得到linkerrust-lldnot found错误。prerequisites.rs对 stderr 中的该关键词做了专门识别utils/wasm-builder/src/prerequisites.rs并输出明确提示rust-lldnot found, please install it!。解决方式是安装并启用带 LLD 的组件通常rustup component add llvm-tools或升级到包含rust-lld的较新工具链。6.3 常见错误缺少runtime_versionWasm 段构建完成后wasm-builder 默认会反序列化生成的 Wasm使用parity-wasm检查是否存在名为runtime_version的自定义段utils/wasm-builder/src/wasm_project.rs。若缺失会报错并提示Couldnt find theruntime_versionwasm section. Please ensure that you are using thesp_version::runtime_versionattribute macro!这是因为该段允许宿主在不执行 Wasm的情况下直接读取RuntimeVersion。Runtime 中必须通过sp_version::runtime_version属性宏声明版本信息对不需要该段的测试用例可调用disable_runtime_version_section_check()关闭此校验。6.4 当找不到Cargo.lock时若构建时无法从OUT_DIR向上找到工作区的Cargo.lockwasm-builder 会打印警告并建议设置WASM_BUILD_WORKSPACE_HINT指向工作区目录utils/wasm-builder/src/wasm_project.rs。七、仓库实战参考标准配置范例bin/node/runtime/build.rs 是 Substrate 自带节点 Runtime 的build.rs采用与 2.2 完全一致的with_current_project()export_heap_base()import_memory()build()写法依赖声明范例bin/node/runtime/Cargo.toml 展示了 optional 的 build-dependency 声明方式其[features]中default [std]stdfeature 聚合了全部 pallet 的std构建 Wasm 时这些 feature 会被自动透传见下节Feature 透传规则wasm-builder 默认启用原生构建中开启的除default与std之外的所有 feature通过CARGO_FEATURE_NAME环境变量探测utils/wasm-builder/src/wasm_project.rs同时支持特殊的runtime-wasmfeature——若项目声明了该 featureWasm 构建时会自动启用未声明则不启用utils/wasm-builder/src/wasm_project.rs可用于在 Wasm 路径下引入no_std特有依赖或切换实现。八、总结substrate-wasm-builder通过 build script 机制把工具链检查 → 生成临时 Wasm 工程 → 交叉编译 → compact/compress → 产物导出 → 增量重编译整条流水线封装为一个链式 API 调用。对 Runtime 开发者而言只需三件事在Cargo.toml的build-dependencies声明optional依赖、编写上文的标准build.rs、在lib.rs中include!生成的wasm_binary.rs即可获得WASM_BINARY与WASM_BINARY_BLOATY两个常量。再配合SKIP_WASM_BUILD、WASM_BUILD_TYPE、WASM_TARGET_DIRECTORY、WASM_BUILD_TOOLCHAIN等环境变量可以精确控制每次构建的产物形态与行为从而适配本地开发、CI 打包、离线构建等不同场景。本文所涉全部配置与行为均可在仓库 utils/wasm-builder 目录下的源码与 bin/node/runtime 实战案例中逐一验证。赞分享区块链开发框架后端【免费下载链接】substrateSubstrate: The platform for blockchain innovators项目地址https://gitcode.com/gh_mirrors/su/substrate点击查看免费下载相关推荐Pyrefly WASM 构建完全指南将 Python 类型检查器编译进浏览器Pyrefly WASM 构建完全指南将 Python 类型检查器编译进浏览器 Pyrefly 除了提供原生 CLI 与语言服务器之外还维护着一个独立的 W开发工具静态分析IDE代码质量Fluent Bit 中基于 WAMR 的 WASM 应用编译使用 clang 编译器与 Docker 构建 wasm 二进制Fluent Bit 中基于 WAMR 的 WASM 应用编译使用 clang 编译器与 Docker 构建 wasm 二进制 导读 本文围绕 Fluent可观测性日志分析云原生流处理Substrate Runtime Interface 完全指南Wasm Runtime 与 Native 节点的 FFI 桥接机制Substrate Runtime Interface 完全指南Wasm Runtime 与 Native 节点的 FFI 桥接机制 导读 本文围绕 Sub区块链开发框架后端上一篇从2秒到200msFAISS版本差异导致的近邻搜索性能异常深度分析下一篇终极视频修复指南如何使用untrunc工具高效恢复损坏的MP4文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考