#lib.wasm

• 类型：

type Wasm =
  | boolean
  | {
      mode?: 'portable' | 'inline' | 'asset' | 'rspack-runtime';
      url?: boolean | { mode?: 'preserve' | 'rewrite' };
      module?: boolean | { enabled?: boolean };
      glue?: boolean | { enabled?: boolean };
      inline?: boolean | 'auto';
      inlineLimit?: number;
      assetFileName?: string;
    };

• 默认值： false

配置 library 产物中的 WebAssembly（.wasm）支持。

#布尔类型

设置 wasm: true 可以使用默认行为启用 WASM 支持：

export default {
  lib: [
    {
      format: 'esm',
      wasm: true,
    },
  ],
};

默认情况下，Rslib 支持：

• new URL('./foo.wasm', import.meta.url) 引用；
• ESM .wasm 导入和重新导出；
• bundleless 产物中通过 new URL() 引用 companion .wasm 资源的本地 JavaScript glue 文件。

设置 wasm: false 或不指定该选项可以关闭 WASM 支持。

#对象类型

使用对象可以自定义 WASM 处理行为：

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        url: true,
        module: true,
        glue: true,
        inline: 'auto',
        inlineLimit: 14 * 1024,
        assetFileName: 'static/wasm/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#wasm.mode

• 类型： 'portable' | 'inline' | 'asset' | 'rspack-runtime'
• 默认值： 'portable'

控制整体 WASM 输出策略。

#portable

默认策略。Rslib 会使用可移植的 ESM 输出处理标准 new URL() 引用、ESM .wasm 导入，以及本地 JavaScript glue 的 companion 资源。

#inline

强制将原始 ESM .wasm 导入的 wasm bytes 内联到生成的 JavaScript facade 中。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'inline',
      },
    },
  ],
};

#asset

强制将原始 ESM .wasm 导入以独立资源文件形式输出，并由生成的 JavaScript facade 加载。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'asset',
      },
    },
  ],
};

#rspack-runtime

使用 Rspack 的 WebAssembly runtime 处理能力，而不是 Rslib 的可移植 WASM 处理逻辑。该模式会启用 Rspack 的 asyncWebAssembly experiment。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'rspack-runtime',
      },
    },
  ],
};

该模式适合你能够控制消费侧应用环境的场景，但不建议作为可移植 library 的默认输出策略。

#wasm.url

• 类型： boolean | { mode?: 'preserve' | 'rewrite' }
• 默认值： true

控制对标准 new URL('./foo.wasm', import.meta.url) 引用的支持。

开启后，Rslib 会扫描 JavaScript 和 TypeScript 模块中的静态 .wasm URL 引用，输出被引用的 .wasm 文件，并根据 wasm.url.mode 保留或重写 URL。

export const wasmUrl = new URL('./foo.wasm', import.meta.url);

设置 wasm.url 为 false 可以关闭该处理。

#wasm.url.mode

• 类型： 'preserve' | 'rewrite'
• 默认值： 'preserve'

'preserve' 会在生成的 JavaScript 产物中保留原始相对请求，并将 .wasm 文件输出到对应位置。

'rewrite' 会使用 wasm.assetFileName 输出 .wasm 文件，并将 URL 改写到输出后的资源路径。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        url: {
          mode: 'rewrite',
        },
        assetFileName: 'static/wasm/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#wasm.module

• 类型： boolean | { enabled?: boolean }
• 默认值： true

控制对 ESM .wasm 导入和重新导出的支持。

import { add } from './add.wasm';

export { add };
export * from './add.wasm';

开启后，Rslib 会将 .wasm 模块转换成 JavaScript ESM facade。这个 facade 会实例化 WebAssembly 模块，并将 wasm exports 重新导出。

设置 wasm.module 为 false 或 { enabled: false } 可以关闭该处理。

#wasm.glue

• 类型： boolean | { enabled?: boolean }
• 默认值： true

控制 bundleless 模式下的本地 JavaScript glue 文件处理。

在 bundled 产物中，JavaScript glue 文件会和其他 JavaScript 模块一样进入模块处理流程，因此标准 new URL('./foo.wasm', import.meta.url) 引用会由 wasm.url 处理。

在 bundleless 产物中，本地 JavaScript glue 文件可能会作为独立文件被保留。开启 wasm.glue 后，Rslib 会扫描这些本地 glue 文件中的标准 new URL() .wasm 引用，并将 companion .wasm 文件输出到对应的 glue 产物旁边。

该选项适用于 wasm-pack --target web 或 wasm-bindgen 等工具生成的 ESM glue，只要生成的 glue 使用 new URL() 引用 companion .wasm 文件。

设置 wasm.glue 为 false 或 { enabled: false } 可以关闭 bundleless glue 扫描。

#wasm.inline

• 类型： boolean | 'auto'
• 默认值： 'auto'

控制是否将原始 ESM .wasm 导入内联到生成的 JavaScript facade 中。

• true：总是内联原始 .wasm module bytes。
• false：不内联原始 .wasm module bytes。
• 'auto'：当文件大小小于或等于 wasm.inlineLimit 时内联原始 .wasm module bytes。

该选项只作用于由 wasm.module 处理的 ESM .wasm 导入，不会 patch 已存在的 JavaScript glue code。

#wasm.inlineLimit

• 类型： number
• 默认值： 14336

wasm.inline: 'auto' 时允许内联的最大文件大小，单位为字节。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        inline: 'auto',
        inlineLimit: 14 * 1024,
      },
    },
  ],
};

#wasm.assetFileName

• 类型： string
• 默认值： 'static/wasm/[name].[contenthash:8][ext]'

输出 .wasm 资源时使用的文件名模板。

支持以下占位符：

• [name]：不包含扩展名的文件名。
• [base]：包含扩展名的文件名。
• [ext]：文件扩展名。
• [hash] 或 [contenthash]：内容哈希。
• [hash:N] 或 [contenthash:N]：长度为 N 的内容哈希。

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        assetFileName: 'assets/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#参考

更多示例、运行时说明，以及 wasm-pack / wasm-bindgen 相关建议，请参考 WebAssembly。