开发工具CLI构建工具WebAssembly【免费下载链接】wasm-pack✨ your favorite rust - wasm workflow tool!项目地址https://gitcode.com/gh_mirrors/wa/wasm-pack点击查看免费下载wasm-pack build是 wasm-pack 工具链的核心命令它负责把 Rust crate 编译为 WebAssembly并生成一套可供 JavaScript 生态直接消费的pkg产物目录wasm 二进制、JS 胶水文件、README.md与package.json。本文将围绕该命令的全部参数展开路径定位、输出目录与命名、构建画像profile、目标环境target、npm scope、安装模式、cargo 参数透传、panic 策略与 64 位 WebAssembly 支持并结合本仓库源码逐项印证每个参数在底层实际如何生效帮助读者把wasm-pack build用透、用准。一、wasm-pack build做什么wasm-pack build命令创建 JavaScript 互操作与 npm 发布所需的全部文件。其核心职责包括将你的 Rust 代码编译为 wasm调用cargo build --lib生成一个pkg目录其中包含wasm 二进制如dom_bg.wasmJS 胶水文件如dom.js你的README.mdpackage.json含 npm 发布所需的元数据与依赖信息。此外pkg目录默认会被自动加入.gitignore——因为它包含的是不应纳入版本控制的构建产物。可以通过--no-gitignore标志关闭这一行为详见下文「跳过 .gitignore」一节。从命令行入口看build在Command枚举中注册且保留了init别名src/command/mod.rs#L28即历史上独立的init命令已被build取代commands 总览 中亦标注其已弃用。wasm-pack build内部通过Build::try_from_opts解析参数、构造Build结构再由Build::run顺序执行一组构建步骤src/command/build.rs#L236-L341。二、内部执行流水线build 命令按顺序做了什么从源码看build命令不是一条单一命令而是一组有序的步骤src/command/build.rs#L343-L390。默认模式normal下执行顺序为step_check_rustc_version检查 rustc 版本--panic-unwind时跳过改用 nightlystep_check_crate_config校验 crate 配置如 crate-type 是否包含cdylib见src/manifest/mod.rs#L544-L547step_check_for_wasm_target检查 wasm 目标是否已安装对 tier-3 目标走单独的检查逻辑step_build_wasm调用cargo build --lib编译 wasmsrc/build/mod.rs#L85-L204step_create_dir创建输出目录并按需写入.gitignoresrc/command/utils.rs#L38-L46step_install_wasm_bindgen依据Cargo.lock解析wasm-bindgen版本并安装对应版本 CLIsrc/command/build.rs#L475-L489step_run_wasm_bindgen执行wasm-bindgen生成 JS/TS 胶水与绑定src/bindgen.rs#L14-L80step_run_wasm_opt除非--no-opt调用wasm-opt优化 wasm 体积step_create_json除非--no-pack生成package.jsonsrc/manifest/mod.rs#L625-L657step_copy_readme / step_copy_license除非--no-pack从 crate 复制 README 与 LICENSE 到产物目录。其中--mode force会跳过前三步检查。整体完成后控制台会输出「Done in X. Your wasm pkg is ready to publish at …」的汇总信息src/command/build.rs#L317-L341。三、Path 参数指定要构建的 cratewasm-pack build接受一个可选的路径参数指向包含Cargo.toml的目录wasm-pack build examples/js-hello-world若给出路径则在该目录下执行构建若未给出路径则在当前目录执行构建。源码层面get_crate_pathsrc/command/utils.rs#L12-L17会在未提供路径时从当前工作目录逐级向上查找Cargo.tomlfind_manifest_from_cwd找到即返回该目录找不到则回退为当前目录并交由后续步骤报出恰当的错误src/command/utils.rs#L22-L36。需要特别注意的是如果你的路径参数以--开头try_from_opts会将其判定为透传给 cargo 的参数而非路径src/command/build.rs#L237-L244。四、输出目录--out-dir默认情况下wasm-pack会在 crate 根目录下生成名为pkg的产物目录。如需自定义使用--out-dir标志wasm-pack build --out-dir out上述命令会把构建产物放到out目录相对 crate 路径解析而不是默认的pkg。源码中out_dir的默认值为pkg且最终路径通过PathClean规范化src/command/build.rs#L247create_pkg_dir在创建目录前还会先清理上一次运行遗留的package.jsonsrc/command/utils.rs#L39-L46。五、生成的文件名--out-name--out-name标志设置输出文件名的前缀。若不提供则使用包名crate name。假设 crate 名为domwasm-pack build # 将生成 # dom.d.ts dom.js dom_bg.d.ts dom_bg.wasm package.json README.md wasm-pack build --out-name index # 将生成 # index.d.ts index.js index_bg.d.ts index_bg.wasm package.json README.md--out-name同时影响package.json中的main、types、files等字段npm_data以name_prefix即包名或 out-name拼出{prefix}_bg.wasm、{prefix}.js、{prefix}.d.ts等文件名src/manifest/mod.rs#L659-L721。测试 tests/all/manifest.rs 验证了--out-name index场景下package.json中main: index.js、types: index.d.ts以及files列表index_bg.wasm、index_bg.js、index.d.ts、index.js的生成结果。六、构建画像 Profile--dev/--profiling/--release/--profilebuild命令接受可选的构建画像参数三者选一--dev、--profiling、--release。若不指定默认使用--release。该参数控制是否启用 debug assertions、是否生成 debug info、以及启用何种程度的优化ProfileDebug AssertionsDebug InfoOptimizationsNotes--devYesYesNo适合开发与调试--profilingNoYesYes适合性能剖析与性能问题调查--releaseNoNoYes适合生产发布--dev使用 cargo 的默认非 release 画像构建更快但对产物优化很少并启用 debug assertions 与运行时正确性检查--profiling与--release都使用 cargo 的 release 画像但前者额外启用 debug info便于在剖析器中定位性能问题上述画像的确切语义会随平台演进而变化。在源码中画像冲突同时给出多个会直接报错try_from_opts中手工实现了互斥校验——只能从--dev、--release、--profiling、--profile name中选择一个src/command/build.rs#L249-L263。另外--debug是已弃用的旧标志等价于--devdev build_opts.dev || build_opts.debugsrc/command/build.rs#L249。底层 cargo 调用差异src/build/mod.rs#L111-L130Dev不加--release走 cargo dev 画像自带 debug infoRelease/Profiling加--releaseCustom(name)加--profile name。同时各画像还对应Cargo.toml中[package.metadata.wasm-pack.profile.*]的配置dev/profiling/release 三段见 cargo-toml-configuration.md可精细控制wasm-opt参数与wasm-bindgen的胶水选项如debug-js-glue、demangle-name-section、dwarf-debug-info、omit-default-module-path、split-linked-modules。configured_profile会按画像从 Cargo.toml 中取对应配置段src/manifest/mod.rs#L533-L541这些选项在wasm_bindgen_build中被转换为--debug、--no-demangle、--keep-debug、--omit-default-module-path、--split-linked-modules等 CLI 参数传给 wasm-bindgensrc/bindgen.rs#L61-L76。说明官方文档表格中描述--profiling启用 debug info从当前仓库实现看profiling 与 release 同样走 cargo 的--release构建DWARF 调试信息默认关闭dwarf-debug-info false如需在剖析时获得调试符号可在 Cargo.toml 的对应 profile 段显式开启。七、目标环境 Target--targetbuild命令接受--target参数用于定制生成的 JS 形态以及 WebAssembly 文件的实例化与加载方式wasm-pack build --target nodejsOptionUsageDescription不指定 或bundler打包器如 Webpack生成适合与 Webpack 等打包器互操作的 JS。通过import引入package.json中指定module键。nodejsNode.js生成使用 CommonJS 模块的 JS配合require使用package.json中指定main键。web浏览器原生生成可被浏览器原生作为 ES module 导入的 JS但 WebAssembly 需手动实例化与加载。no-modules浏览器原生与web相同但 JS 直接以脚本方式引入页面并修改全局状态且支持的wasm-bindgen特性不如web多。denoDeno生成可被 Deno 原生以 ES module 导入的 JS。源码层面Target枚举包含Bundler、Web、Nodejs、NoModules、Deno五种src/command/build.rs#L52-L70默认值为Bundler解析时还接受browser作为bundler的别名src/command/build.rs#L91-L103。各 target 对package.json的影响在write_package_json中按目标分派src/manifest/mod.rs#L643-L650nodejs→CommonJSPackage使用main键CommonJS 模块bundler→ESModulesPackagetype: module、main指向 JS 胶水并附带sideEffects声明web→ESModulesPackage同样为 ES module 形态sideEffects仅含./snippets/*no-modules→NoModulesPackage使用browser键deno→不生成 package.jsonDeno 直接导入无需 npm 清单。关于sideEffects官方文档表格标注 bundler 目标「sideEffects: false是默认」但当前仓库实现中 bundler 目标实际写入sideEffects: [./{main}.js, ./snippets/*]src/manifest/mod.rs#L790web 目标写入[./snippets/*]src/manifest/mod.rs#L823测试也验证了这一行为tests/all/manifest.rs。这些条目用于告诉打包器哪些文件带副作用、不可被 tree-shaking 移除。另外wasm_bindgen_build在向 wasm-bindgen 传递--target时做了版本兼容若本机 wasm-bindgen CLI 版本低于 0.2.40则改用旧式参数如--nodejs、--no-modules、--web并提示升级src/bindgen.rs#L93-L120。八、npm Scope--scopebuild命令接受可选的--scope参数为包名添加 npm scope。如果你的包名可能与公共 registry 中的现有包冲突这一参数很有用wasm-pack build examples/js-hello-world --scope test该命令生成的package.json中包名为test/js-hello-world。源码中npm_data在给定 scope 时拼接为{scope}/{name}src/manifest/mod.rs#L678-L681--scope的短选项为-ssrc/command/build.rs#L127-L129。九、安装模式 Mode--modebuild命令接受可选的--mode参数wasm-pack build examples/js-hello-world --mode no-installOptionDescriptionno-install构建并生成 wasm 绑定但不安装wasm-bindgen依赖环境中已有的全局版本。normal在no-install全部行为的基础上使用必要时安装wasm-bindgen。InstallMode枚举定义于src/install/mode.rs#L6-L33另有第三个取值force跳过 rustc 版本检查且允许安装。install_permitted()决定构建过程中是否允许自动安装工具normal与force允许no-install不允许src/install/mode.rs#L35-L43。默认值为normalsrc/command/build.rs#L131。十、Extra options把参数直接透传给 cargobuild命令可以把 wasm-pack 不认识的额外参数原样透传给cargo build。用法是把这些参数追加在命令最末尾、--之后就像直接调用cargo build一样。例如利用 cargo 的离线特性构建wasm-pack build examples/js-hello-world --mode no-install -- --offline底层实现上BuildOptions声明了allow_hyphen_values与trailing_var_arg--之后的内容全部进入extra_optionssrc/command/build.rs#L121随后传给cargo_build_wasm。cargo_build_wasm还有一个贴心处理由于 cargo 在 crate 目录内执行相对路径参数会失效因此它会将--target-dir、--out-dir、--manifest-path后续的相对路径值自动转换为绝对路径src/build/mod.rs#L147-L166。十一、跳过 .gitignore--no-gitignore默认情况下wasm-pack会在输出目录中创建一个内容为*的.gitignore文件阻止构建产物被纳入版本控制。若你希望把pkg目录提交到仓库例如用于 GitHub Pages、Deno 包或 monorepo 场景可以用--no-gitignore跳过该文件的生成wasm-pack build --no-gitignore该标志对--target web等其他 target 同样适用。源码中create_pkg_dir在no_gitignore false时写入*src/command/utils.rs#L39-L46。注如果你需要在pkg目录和 npm 包中额外附带其他资产官方文档表示正在规划专门方案眼下可通过--no-gitignore保留这些文件。十二、Panic 策略--panic-unwind默认情况下Rust 在 WebAssembly 中的 panic 以panicabort编译panic 会直接中止 WebAssembly 实例。--panic-unwind标志改变这一行为使 panic 可以在 FFI 边界被捕获并由wasm-bindgen的 catch-unwind 支持转换为 JavaScript 异常wasm-pack build --panic-unwind该标志会使用nightly工具链调用 cargocargo nightly build追加-Z build-stdstd,panic_unwind以带 unwind 支持重新构建std设置RUSTFLAGS-Cpanicunwind保留用户已有的RUSTFLAGS。首次使用--panic-unwind时wasm-pack会通过rustup自动安装缺失的前置条件nightly 工具链nightly 的rust-src组件nightly 的wasm32-unknown-unknown目标。如果你不使用rustup则必须手动安装这些前置条件参见 Non-rustup setups。源码印证cargo_build_wasm中nightly必须是 cargo 的第一个参数随后依次追加-Z build-stdstd,panic_unwind与合并后的RUSTFLAGS-Cpanicunwindsrc/build/mod.rs#L101-L145前置检查由check_nightly_prerequisites完成src/build/wasm_target.rs#L242起。当启用该标志时第一步的 rustc 版本检查会被跳过src/command/build.rs#L392-L404。重要提示wasm-pack只负责产出.wasm。「panic 可恢复的 JavaScript 异常」这一行为还需要绑定层的运行时胶水如wasm-bindgen的 catch-unwind 特性。如果只使用--panic-unwind而没有运行时胶水panic 依然会终止实例——只是从abort变成了unwind。--panic-unwind同样适用于wasm-pack test。十三、64 位 WebAssemblywasm64-unknown-unknowncargo 的目标三元组target triple是 wasm-pack 构建哪种 WebAssembly ABI 的事实来源。要产出memory64二进制请用 cargo 原生方式声明目标——三选一# .cargo/config.toml [build] target wasm64-unknown-unknown或作为透传的 cargo 参数wasm-pack build -- --target wasm64-unknown-unknown或通过环境变量CARGO_BUILD_TARGETwasm64-unknown-unknown。wasm64-unknown-unknown是 Rust 的 tier-3 目标rustup没有为其提供预编译产物需要你通过 cargo 原生配置自行提供两样东西1. nightly 工具链——rust-toolchain.toml是 cargo 原生方式将项目锁定到 nightly# rust-toolchain.toml [toolchain] channel nightly components [rust-src]或者为一次性调用设置RUSTUP_TOOLCHAINnightly。2.-Z build-std从源码构建std因为没有预编译版本。在.cargo/config.toml中添加[unstable] build-std [std, panic_abort]或者以透传 cargo 参数方式传递-Z build-stdstd,panic_abort。wasm-pack 自身的定位它不会插手 cargo 调用——不会注入nightly或-Z build-std那会覆盖你的工具链锁定或让未打算使用 nightly 的用户感到意外。当它检测到wasm64-*目标三元组时只做这几件事校验当前生效工具链是否为 nightly若不是则给出指向上述配置的明确错误提示若当前工具链缺少rust-src组件通过rustup自动安装不会尝试rustup target add wasm64-*tier-3 目标该操作必然失败向wasm-opt传递--enable-memory64让优化器接受 64 位内存与表。源码印证目标三元组的解析优先级完全复刻 cargosrc/command/build.rs#L274-L285——① 透传参数中的--target ②CARGO_BUILD_TARGET环境变量 ③.cargo/config.toml的[build] target自 crate 目录向上逐级查找再回退到$CARGO_HOME/config.toml见read_cargo_build_targetsrc/command/build.rs#L544-L569 ④ 回退wasm32-unknown-unknowntier-3 前置检查在check_tier3_wasm_prerequisites中实现src/build/wasm_target.rs#L80-L103--enable-memory64注入于step_run_wasm_optsrc/command/build.rs#L509-L535。此外wasm-opt对 64 位内存的支持要求 binaryen 版本不低于 118相关约束见 tests/all/download.rs。十四、其他值得了解的构建标志除上述主参数外BuildOptionssrc/command/build.rs#L119-L204还定义了以下实用标志标志说明--no-typescript默认会为生成的 JS 生成*.d.ts类型声明此标志关闭之对应 wasm-bindgen 的--no-typescript见src/bindgen.rs#L28-L32。--weak-refs启用 JS weak references 提案传递给 wasm-bindgen 的--weak-refssrc/bindgen.rs#L42-L44。--reference-types启用 WebAssembly reference types传递给 wasm-bindgen 的--reference-types同时为wasm-opt追加--enable-reference-typessrc/command/build.rs#L518-L520。--no-pack别名--no-package不生成package.json同时跳过 README 与 LICENSE 的复制见get_process_stepssrc/command/build.rs#L381-L387。--no-opt别名--no-optimization跳过wasm-opt优化步骤src/command/build.rs#L377-L379。若wasm-opt执行失败报错信息会提示可在 Cargo.toml 的package.metadata.wasm-pack中设置wasm-opt false关闭src/command/build.rs#L530-L534。另外全局日志级别也可用于构建调试wasm-pack --log-level error build、wasm-pack --quiet build、wasm-pack --verbose build这些全局标志必须位于命令之前详见 commands 总览。十五、典型组合速查综合以上参数一个生产发布级别的构建可以是# 生产构建输出到 out 目录使用自定义前缀针对打包器场景 wasm-pack build --release --target bundler --out-dir out --out-name index需要提交pkg到仓库如 monorepo 中的 GitHub Pages 或 Deno 发布时wasm-pack build --no-gitignore要获得可在 Node.js 中require的 CommonJS 包wasm-pack build --target nodejs需要捕获 Rust panic 并转为 JS 异常配合 wasm-bindgen 的 catch-unwind 运行时胶水wasm-pack build --panic-unwind需要memory64的 64 位 wasm配合 nightly 工具链与 build-std 配置wasm-pack build -- --target wasm64-unknown-unknownwasm-pack build是 wasm-pack 工作流的中枢理解其参数矩阵与底层步骤流水线就能精准控制产物的形态打包器/Node/浏览器/Deno、优化程度dev/profiling/release、命名与输出位置从而把「Rust → wasm → npm」这条链路做到开箱即用、可发布、可调试。赞分享开发工具CLI构建工具WebAssembly【免费下载链接】wasm-pack✨ your favorite rust - wasm workflow tool!项目地址https://gitcode.com/gh_mirrors/wa/wasm-pack点击查看免费下载相关推荐构建 microsoft/fast-build 的 Rust/WASM 核心从 cargo 到 wasm-pack 的完整开发指南构建 microsoft/fast build 的 Rust/WASM 核心从 cargo 到 wasm pack 的完整开发指南 microsoft/f前端UI组件Rye build 命令详解从源码到分发包的完整构建流程Rye build 命令详解从源码到分发包的完整构建流程 导读 本篇文章基于当前仓库中 docs/guide/commands/build.md https:开发工具CLI告别臃肿的协作软件十分钟用 Nullboard 搭出专属极简看板告别臃肿的协作软件十分钟用 Nullboard 搭出专属极简看板 你是不是也遇到过这样的场景想管理自己的任务清单结果下载了一堆大而全的项目管理工具光创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wasm-pack build 命令完全指南：从 Rust crate 到可发布 npm 包的完整构建流程
开发工具CLI构建工具WebAssembly【免费下载链接】wasm-pack✨ your favorite rust - wasm workflow tool!项目地址https://gitcode.com/gh_mirrors/wa/wasm-pack点击查看免费下载wasm-pack build是 wasm-pack 工具链的核心命令它负责把 Rust crate 编译为 WebAssembly并生成一套可供 JavaScript 生态直接消费的pkg产物目录wasm 二进制、JS 胶水文件、README.md与package.json。本文将围绕该命令的全部参数展开路径定位、输出目录与命名、构建画像profile、目标环境target、npm scope、安装模式、cargo 参数透传、panic 策略与 64 位 WebAssembly 支持并结合本仓库源码逐项印证每个参数在底层实际如何生效帮助读者把wasm-pack build用透、用准。一、wasm-pack build做什么wasm-pack build命令创建 JavaScript 互操作与 npm 发布所需的全部文件。其核心职责包括将你的 Rust 代码编译为 wasm调用cargo build --lib生成一个pkg目录其中包含wasm 二进制如dom_bg.wasmJS 胶水文件如dom.js你的README.mdpackage.json含 npm 发布所需的元数据与依赖信息。此外pkg目录默认会被自动加入.gitignore——因为它包含的是不应纳入版本控制的构建产物。可以通过--no-gitignore标志关闭这一行为详见下文「跳过 .gitignore」一节。从命令行入口看build在Command枚举中注册且保留了init别名src/command/mod.rs#L28即历史上独立的init命令已被build取代commands 总览 中亦标注其已弃用。wasm-pack build内部通过Build::try_from_opts解析参数、构造Build结构再由Build::run顺序执行一组构建步骤src/command/build.rs#L236-L341。二、内部执行流水线build 命令按顺序做了什么从源码看build命令不是一条单一命令而是一组有序的步骤src/command/build.rs#L343-L390。默认模式normal下执行顺序为step_check_rustc_version检查 rustc 版本--panic-unwind时跳过改用 nightlystep_check_crate_config校验 crate 配置如 crate-type 是否包含cdylib见src/manifest/mod.rs#L544-L547step_check_for_wasm_target检查 wasm 目标是否已安装对 tier-3 目标走单独的检查逻辑step_build_wasm调用cargo build --lib编译 wasmsrc/build/mod.rs#L85-L204step_create_dir创建输出目录并按需写入.gitignoresrc/command/utils.rs#L38-L46step_install_wasm_bindgen依据Cargo.lock解析wasm-bindgen版本并安装对应版本 CLIsrc/command/build.rs#L475-L489step_run_wasm_bindgen执行wasm-bindgen生成 JS/TS 胶水与绑定src/bindgen.rs#L14-L80step_run_wasm_opt除非--no-opt调用wasm-opt优化 wasm 体积step_create_json除非--no-pack生成package.jsonsrc/manifest/mod.rs#L625-L657step_copy_readme / step_copy_license除非--no-pack从 crate 复制 README 与 LICENSE 到产物目录。其中--mode force会跳过前三步检查。整体完成后控制台会输出「Done in X. Your wasm pkg is ready to publish at …」的汇总信息src/command/build.rs#L317-L341。三、Path 参数指定要构建的 cratewasm-pack build接受一个可选的路径参数指向包含Cargo.toml的目录wasm-pack build examples/js-hello-world若给出路径则在该目录下执行构建若未给出路径则在当前目录执行构建。源码层面get_crate_pathsrc/command/utils.rs#L12-L17会在未提供路径时从当前工作目录逐级向上查找Cargo.tomlfind_manifest_from_cwd找到即返回该目录找不到则回退为当前目录并交由后续步骤报出恰当的错误src/command/utils.rs#L22-L36。需要特别注意的是如果你的路径参数以--开头try_from_opts会将其判定为透传给 cargo 的参数而非路径src/command/build.rs#L237-L244。四、输出目录--out-dir默认情况下wasm-pack会在 crate 根目录下生成名为pkg的产物目录。如需自定义使用--out-dir标志wasm-pack build --out-dir out上述命令会把构建产物放到out目录相对 crate 路径解析而不是默认的pkg。源码中out_dir的默认值为pkg且最终路径通过PathClean规范化src/command/build.rs#L247create_pkg_dir在创建目录前还会先清理上一次运行遗留的package.jsonsrc/command/utils.rs#L39-L46。五、生成的文件名--out-name--out-name标志设置输出文件名的前缀。若不提供则使用包名crate name。假设 crate 名为domwasm-pack build # 将生成 # dom.d.ts dom.js dom_bg.d.ts dom_bg.wasm package.json README.md wasm-pack build --out-name index # 将生成 # index.d.ts index.js index_bg.d.ts index_bg.wasm package.json README.md--out-name同时影响package.json中的main、types、files等字段npm_data以name_prefix即包名或 out-name拼出{prefix}_bg.wasm、{prefix}.js、{prefix}.d.ts等文件名src/manifest/mod.rs#L659-L721。测试 tests/all/manifest.rs 验证了--out-name index场景下package.json中main: index.js、types: index.d.ts以及files列表index_bg.wasm、index_bg.js、index.d.ts、index.js的生成结果。六、构建画像 Profile--dev/--profiling/--release/--profilebuild命令接受可选的构建画像参数三者选一--dev、--profiling、--release。若不指定默认使用--release。该参数控制是否启用 debug assertions、是否生成 debug info、以及启用何种程度的优化ProfileDebug AssertionsDebug InfoOptimizationsNotes--devYesYesNo适合开发与调试--profilingNoYesYes适合性能剖析与性能问题调查--releaseNoNoYes适合生产发布--dev使用 cargo 的默认非 release 画像构建更快但对产物优化很少并启用 debug assertions 与运行时正确性检查--profiling与--release都使用 cargo 的 release 画像但前者额外启用 debug info便于在剖析器中定位性能问题上述画像的确切语义会随平台演进而变化。在源码中画像冲突同时给出多个会直接报错try_from_opts中手工实现了互斥校验——只能从--dev、--release、--profiling、--profile name中选择一个src/command/build.rs#L249-L263。另外--debug是已弃用的旧标志等价于--devdev build_opts.dev || build_opts.debugsrc/command/build.rs#L249。底层 cargo 调用差异src/build/mod.rs#L111-L130Dev不加--release走 cargo dev 画像自带 debug infoRelease/Profiling加--releaseCustom(name)加--profile name。同时各画像还对应Cargo.toml中[package.metadata.wasm-pack.profile.*]的配置dev/profiling/release 三段见 cargo-toml-configuration.md可精细控制wasm-opt参数与wasm-bindgen的胶水选项如debug-js-glue、demangle-name-section、dwarf-debug-info、omit-default-module-path、split-linked-modules。configured_profile会按画像从 Cargo.toml 中取对应配置段src/manifest/mod.rs#L533-L541这些选项在wasm_bindgen_build中被转换为--debug、--no-demangle、--keep-debug、--omit-default-module-path、--split-linked-modules等 CLI 参数传给 wasm-bindgensrc/bindgen.rs#L61-L76。说明官方文档表格中描述--profiling启用 debug info从当前仓库实现看profiling 与 release 同样走 cargo 的--release构建DWARF 调试信息默认关闭dwarf-debug-info false如需在剖析时获得调试符号可在 Cargo.toml 的对应 profile 段显式开启。七、目标环境 Target--targetbuild命令接受--target参数用于定制生成的 JS 形态以及 WebAssembly 文件的实例化与加载方式wasm-pack build --target nodejsOptionUsageDescription不指定 或bundler打包器如 Webpack生成适合与 Webpack 等打包器互操作的 JS。通过import引入package.json中指定module键。nodejsNode.js生成使用 CommonJS 模块的 JS配合require使用package.json中指定main键。web浏览器原生生成可被浏览器原生作为 ES module 导入的 JS但 WebAssembly 需手动实例化与加载。no-modules浏览器原生与web相同但 JS 直接以脚本方式引入页面并修改全局状态且支持的wasm-bindgen特性不如web多。denoDeno生成可被 Deno 原生以 ES module 导入的 JS。源码层面Target枚举包含Bundler、Web、Nodejs、NoModules、Deno五种src/command/build.rs#L52-L70默认值为Bundler解析时还接受browser作为bundler的别名src/command/build.rs#L91-L103。各 target 对package.json的影响在write_package_json中按目标分派src/manifest/mod.rs#L643-L650nodejs→CommonJSPackage使用main键CommonJS 模块bundler→ESModulesPackagetype: module、main指向 JS 胶水并附带sideEffects声明web→ESModulesPackage同样为 ES module 形态sideEffects仅含./snippets/*no-modules→NoModulesPackage使用browser键deno→不生成 package.jsonDeno 直接导入无需 npm 清单。关于sideEffects官方文档表格标注 bundler 目标「sideEffects: false是默认」但当前仓库实现中 bundler 目标实际写入sideEffects: [./{main}.js, ./snippets/*]src/manifest/mod.rs#L790web 目标写入[./snippets/*]src/manifest/mod.rs#L823测试也验证了这一行为tests/all/manifest.rs。这些条目用于告诉打包器哪些文件带副作用、不可被 tree-shaking 移除。另外wasm_bindgen_build在向 wasm-bindgen 传递--target时做了版本兼容若本机 wasm-bindgen CLI 版本低于 0.2.40则改用旧式参数如--nodejs、--no-modules、--web并提示升级src/bindgen.rs#L93-L120。八、npm Scope--scopebuild命令接受可选的--scope参数为包名添加 npm scope。如果你的包名可能与公共 registry 中的现有包冲突这一参数很有用wasm-pack build examples/js-hello-world --scope test该命令生成的package.json中包名为test/js-hello-world。源码中npm_data在给定 scope 时拼接为{scope}/{name}src/manifest/mod.rs#L678-L681--scope的短选项为-ssrc/command/build.rs#L127-L129。九、安装模式 Mode--modebuild命令接受可选的--mode参数wasm-pack build examples/js-hello-world --mode no-installOptionDescriptionno-install构建并生成 wasm 绑定但不安装wasm-bindgen依赖环境中已有的全局版本。normal在no-install全部行为的基础上使用必要时安装wasm-bindgen。InstallMode枚举定义于src/install/mode.rs#L6-L33另有第三个取值force跳过 rustc 版本检查且允许安装。install_permitted()决定构建过程中是否允许自动安装工具normal与force允许no-install不允许src/install/mode.rs#L35-L43。默认值为normalsrc/command/build.rs#L131。十、Extra options把参数直接透传给 cargobuild命令可以把 wasm-pack 不认识的额外参数原样透传给cargo build。用法是把这些参数追加在命令最末尾、--之后就像直接调用cargo build一样。例如利用 cargo 的离线特性构建wasm-pack build examples/js-hello-world --mode no-install -- --offline底层实现上BuildOptions声明了allow_hyphen_values与trailing_var_arg--之后的内容全部进入extra_optionssrc/command/build.rs#L121随后传给cargo_build_wasm。cargo_build_wasm还有一个贴心处理由于 cargo 在 crate 目录内执行相对路径参数会失效因此它会将--target-dir、--out-dir、--manifest-path后续的相对路径值自动转换为绝对路径src/build/mod.rs#L147-L166。十一、跳过 .gitignore--no-gitignore默认情况下wasm-pack会在输出目录中创建一个内容为*的.gitignore文件阻止构建产物被纳入版本控制。若你希望把pkg目录提交到仓库例如用于 GitHub Pages、Deno 包或 monorepo 场景可以用--no-gitignore跳过该文件的生成wasm-pack build --no-gitignore该标志对--target web等其他 target 同样适用。源码中create_pkg_dir在no_gitignore false时写入*src/command/utils.rs#L39-L46。注如果你需要在pkg目录和 npm 包中额外附带其他资产官方文档表示正在规划专门方案眼下可通过--no-gitignore保留这些文件。十二、Panic 策略--panic-unwind默认情况下Rust 在 WebAssembly 中的 panic 以panicabort编译panic 会直接中止 WebAssembly 实例。--panic-unwind标志改变这一行为使 panic 可以在 FFI 边界被捕获并由wasm-bindgen的 catch-unwind 支持转换为 JavaScript 异常wasm-pack build --panic-unwind该标志会使用nightly工具链调用 cargocargo nightly build追加-Z build-stdstd,panic_unwind以带 unwind 支持重新构建std设置RUSTFLAGS-Cpanicunwind保留用户已有的RUSTFLAGS。首次使用--panic-unwind时wasm-pack会通过rustup自动安装缺失的前置条件nightly 工具链nightly 的rust-src组件nightly 的wasm32-unknown-unknown目标。如果你不使用rustup则必须手动安装这些前置条件参见 Non-rustup setups。源码印证cargo_build_wasm中nightly必须是 cargo 的第一个参数随后依次追加-Z build-stdstd,panic_unwind与合并后的RUSTFLAGS-Cpanicunwindsrc/build/mod.rs#L101-L145前置检查由check_nightly_prerequisites完成src/build/wasm_target.rs#L242起。当启用该标志时第一步的 rustc 版本检查会被跳过src/command/build.rs#L392-L404。重要提示wasm-pack只负责产出.wasm。「panic 可恢复的 JavaScript 异常」这一行为还需要绑定层的运行时胶水如wasm-bindgen的 catch-unwind 特性。如果只使用--panic-unwind而没有运行时胶水panic 依然会终止实例——只是从abort变成了unwind。--panic-unwind同样适用于wasm-pack test。十三、64 位 WebAssemblywasm64-unknown-unknowncargo 的目标三元组target triple是 wasm-pack 构建哪种 WebAssembly ABI 的事实来源。要产出memory64二进制请用 cargo 原生方式声明目标——三选一# .cargo/config.toml [build] target wasm64-unknown-unknown或作为透传的 cargo 参数wasm-pack build -- --target wasm64-unknown-unknown或通过环境变量CARGO_BUILD_TARGETwasm64-unknown-unknown。wasm64-unknown-unknown是 Rust 的 tier-3 目标rustup没有为其提供预编译产物需要你通过 cargo 原生配置自行提供两样东西1. nightly 工具链——rust-toolchain.toml是 cargo 原生方式将项目锁定到 nightly# rust-toolchain.toml [toolchain] channel nightly components [rust-src]或者为一次性调用设置RUSTUP_TOOLCHAINnightly。2.-Z build-std从源码构建std因为没有预编译版本。在.cargo/config.toml中添加[unstable] build-std [std, panic_abort]或者以透传 cargo 参数方式传递-Z build-stdstd,panic_abort。wasm-pack 自身的定位它不会插手 cargo 调用——不会注入nightly或-Z build-std那会覆盖你的工具链锁定或让未打算使用 nightly 的用户感到意外。当它检测到wasm64-*目标三元组时只做这几件事校验当前生效工具链是否为 nightly若不是则给出指向上述配置的明确错误提示若当前工具链缺少rust-src组件通过rustup自动安装不会尝试rustup target add wasm64-*tier-3 目标该操作必然失败向wasm-opt传递--enable-memory64让优化器接受 64 位内存与表。源码印证目标三元组的解析优先级完全复刻 cargosrc/command/build.rs#L274-L285——① 透传参数中的--target ②CARGO_BUILD_TARGET环境变量 ③.cargo/config.toml的[build] target自 crate 目录向上逐级查找再回退到$CARGO_HOME/config.toml见read_cargo_build_targetsrc/command/build.rs#L544-L569 ④ 回退wasm32-unknown-unknowntier-3 前置检查在check_tier3_wasm_prerequisites中实现src/build/wasm_target.rs#L80-L103--enable-memory64注入于step_run_wasm_optsrc/command/build.rs#L509-L535。此外wasm-opt对 64 位内存的支持要求 binaryen 版本不低于 118相关约束见 tests/all/download.rs。十四、其他值得了解的构建标志除上述主参数外BuildOptionssrc/command/build.rs#L119-L204还定义了以下实用标志标志说明--no-typescript默认会为生成的 JS 生成*.d.ts类型声明此标志关闭之对应 wasm-bindgen 的--no-typescript见src/bindgen.rs#L28-L32。--weak-refs启用 JS weak references 提案传递给 wasm-bindgen 的--weak-refssrc/bindgen.rs#L42-L44。--reference-types启用 WebAssembly reference types传递给 wasm-bindgen 的--reference-types同时为wasm-opt追加--enable-reference-typessrc/command/build.rs#L518-L520。--no-pack别名--no-package不生成package.json同时跳过 README 与 LICENSE 的复制见get_process_stepssrc/command/build.rs#L381-L387。--no-opt别名--no-optimization跳过wasm-opt优化步骤src/command/build.rs#L377-L379。若wasm-opt执行失败报错信息会提示可在 Cargo.toml 的package.metadata.wasm-pack中设置wasm-opt false关闭src/command/build.rs#L530-L534。另外全局日志级别也可用于构建调试wasm-pack --log-level error build、wasm-pack --quiet build、wasm-pack --verbose build这些全局标志必须位于命令之前详见 commands 总览。十五、典型组合速查综合以上参数一个生产发布级别的构建可以是# 生产构建输出到 out 目录使用自定义前缀针对打包器场景 wasm-pack build --release --target bundler --out-dir out --out-name index需要提交pkg到仓库如 monorepo 中的 GitHub Pages 或 Deno 发布时wasm-pack build --no-gitignore要获得可在 Node.js 中require的 CommonJS 包wasm-pack build --target nodejs需要捕获 Rust panic 并转为 JS 异常配合 wasm-bindgen 的 catch-unwind 运行时胶水wasm-pack build --panic-unwind需要memory64的 64 位 wasm配合 nightly 工具链与 build-std 配置wasm-pack build -- --target wasm64-unknown-unknownwasm-pack build是 wasm-pack 工作流的中枢理解其参数矩阵与底层步骤流水线就能精准控制产物的形态打包器/Node/浏览器/Deno、优化程度dev/profiling/release、命名与输出位置从而把「Rust → wasm → npm」这条链路做到开箱即用、可发布、可调试。赞分享开发工具CLI构建工具WebAssembly【免费下载链接】wasm-pack✨ your favorite rust - wasm workflow tool!项目地址https://gitcode.com/gh_mirrors/wa/wasm-pack点击查看免费下载相关推荐构建 microsoft/fast-build 的 Rust/WASM 核心从 cargo 到 wasm-pack 的完整开发指南构建 microsoft/fast build 的 Rust/WASM 核心从 cargo 到 wasm pack 的完整开发指南 microsoft/f前端UI组件Rye build 命令详解从源码到分发包的完整构建流程Rye build 命令详解从源码到分发包的完整构建流程 导读 本篇文章基于当前仓库中 docs/guide/commands/build.md https:开发工具CLI告别臃肿的协作软件十分钟用 Nullboard 搭出专属极简看板告别臃肿的协作软件十分钟用 Nullboard 搭出专属极简看板 你是不是也遇到过这样的场景想管理自己的任务清单结果下载了一堆大而全的项目管理工具光创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考