wasm_module_new 返回 null 主因是模块损坏、wasi 版本不兼容或内存传参错误；需用 wasm-validate 校验、启用 wasipreview1compat、固定非托管内存。
用 Wasmtime 加载 .wasm 文件时，wasm_module_new 返回 NULL 怎么办
常见错误是传入了损坏、未对齐或非 WASI 兼容的二进制内容。Wasmtime 对模块格式非常严格，尤其当模块由 C# 编译生成时，若未启用 WASI 支持或导出符号不匹配，wasm_module_new 会静默失败并返回 NULL。
实操建议：
- 先用
wasm-validate（来自wabt工具集）校验module.wasm：运行wabt-validate module.wasm，确认输出 “ok” - 确保 C# 项目使用
Wasi.Sdk且目标框架为net7.0或更高；csproj中需显式包含<wasiruntime>true</wasiruntime> - 加载前检查字节长度：Wasmtime 要求
wasm_byte_vec_t的size字段必须精确等于文件实际字节数，多一个 \0 或少一个字节都会失败 - 不要直接从
File.ReadAllBytes()后裸传指针——C# 的 GC 可能移动内存，务必用fixed固定或复制到Marshal.AllocHGlobal分配的非托管内存
从 C# 调用导出函数时，m3_CallWithArgs 崩溃或返回乱码值
这通常不是函数逻辑问题，而是调用约定与内存布局错位所致。Wasm3 等轻量运行时默认按 C ABI 处理参数，但 C# 生成的 WASM 若未导出带签名的函数（如 _add），或参数类型未对齐（比如传 int 却期望 i32），就会触发栈破坏。
实操建议：
- 导出函数名必须带下划线前缀，且在 C# 中用
[UnmanagedCallersOnly(EntryPoint = "_add")]显式声明，不能依赖自动名称修饰 - 所有参数和返回值强制使用
int、uint、long等与 WebAssembly 整数类型一一对应的类型；避免bool、string、struct - 若需传字符串或数组，必须手动管理线性内存：先调用
_malloc分配空间，用Marshal.Copy写入数据，再把偏移地址（而非托管引用）传给 Wasm 函数 - 调用后立即检查
m3_GetResults，不要假设返回值就在栈顶——Wasm3 的runtime->stack是内部实现细节，不稳定
Wasi.Sdk 生成的 .wasm 无法被 Wasmtime 正确加载，报错 unknown import: wasi_snapshot_preview1
这是最典型的兼容性断裂点。C# 使用 Wasi.Sdk 默认链接的是 wasi_snapshot_preview1 接口，而新版 Wasmtime（v14+）已默认禁用该旧版 WASI，只支持 wasi:io/streams 等新接口族。
实操建议：
- 降级 Wasmtime 到 v13.x（如
wasmtime-13.0.1），它仍默认启用 preview1 支持 - 或升级 C# 构建配置：在
csproj中添加<wasipreview1compat>true</wasipreview1compat>，并确保 SDK 版本 ≥0.1.4-preview.10020 - 启动 Wasmtime 时加
--wasi-preview1参数（仅限 CLI 场景）；若用 C API，则初始化wasm_config_t后调用wasmtime_config_wasi_preview1_set(config, true) - 注意：WASI 不是可选插件，而是模块能力契约——若 C# 模块调用了
path_open等系统调用，运行时就必须提供对应实现，否则加载即失败
Blazor WebAssembly 项目里想复用已有 .wasm 模块，但 DotNet.invokeMethodAsync 找不到函数
Blazor WASM 运行时（dotnet.wasm）本身就是一个 WebAssembly 模块，但它不支持动态加载外部 .wasm 文件。你看到的 DotNet.invokeMethodAsync 只能调用 C# 托管方法，不能穿透到另一个独立编译的 .wasm 模块中。
实操建议：
- 放弃“在 Blazor 里加载外部 .wasm”的想法——这不是设计目标，也没有标准 API 支持
- 若需混合能力，应将 C/C++ 逻辑用 Emscripten 编译为 JS glue + wasm，并通过
JSInvokable封装成 JS 函数，再由 C# 调用IJSRuntime.InvokeVoidAsync - 或者反向操作：把 C# 逻辑编译为 WASM（用
Wasi.Sdk），再用 JavaScript（如WebAssembly.instantiateStreaming）加载，最后由 Blazor 的 JS interop 桥接调用 - 关键区别在于：Blazor 的 WASM 是托管运行时，而 Emscripten/Wasmtime 的 WASM 是非托管沙箱——两者内存空间、调用栈、GC 机制完全隔离，不能混用
WASI 接口版本错配、托管/非托管内存边界、导出符号命名规则——这三个点几乎覆盖了 90% 的 C# 调用 Wasm 失败场景。它们不体现在文档首页，却真实卡在每次 wasm_instance_new 返回空指针的那一刻。
