WebAssembly AI 插件热加载：运行时替换模块而不丢会话状态

发布时间：2026/7/7 4:53:13

WebAssembly AI 插件热加载：运行时替换模块而不丢会话状态

一、插件升级需要刷新页面，这是用户的代价

在浏览器里跑 AI 推理时，插件通常以 WASM 模块形式加载。用户可能正在跟一个文本生成插件对话，聊了十几轮，上下文中累积了丰富的推理状态——模型权重已预热、注意力缓存已经建立、提示词模板也已定制好。这时候如果插件有新版本需要升级，传统做法只有一个：刷新页面。

刷新页面的后果很清楚。WASM 线性内存被整体丢弃，所有会话上下文、推理中间状态、用户配置全部消失。用户需要重新输入、重新预热模型、重新建立上下文。对于浏览器端 AI 应用来说，这不只是"重新加载"的问题，而是整个会话的断裂。

真正的问题是：WASM 模块本质上是一块内存空间加一组导出函数。能不能在不销毁宿主页面的前提下，把旧模块的状态完整迁移到新模块里？这就是热加载要解决的核心——运行时替换模块，同时保留会话状态。

二、时序：停用旧模块、序列化状态、加载新模块、恢复状态

热加载的核心不是"怎么换模块"，而是"状态怎么带着走"。WASM 模块本身不持有持久状态，但模块内部的全局变量、堆分配的数据结构和外部通过共享内存注入的数据，都是状态的一部分。流程上可以拆成四步。

sequenceDiagram participant Host as 宿主(JS) participant Old as 旧插件模块(WASM) participant Store as 序列化存储(内存/IndexedDB) participant New as 新插件模块(WASM) Host->>Old: 1. 停用：停止所有待处理推理任务 Old-->>Host: 等待进行中的任务完成或取消 Host->>Old: 2. 导出状态：调用 export_state() Old->>Old: 将全局状态、缓存、配置写入线性内存 Old-->>Host: 返回状态数据的指针和长度 Host->>Store: 3. 持久化：从 WASM 线性内存读取数据并保存 Host->>Old: 释放旧模块实例（drop） Host->>New: 4. 加载：实例化新版本插件模块 Host->>Store: 5. 读取：获取之前保存的状态数据 Host->>New: 6. 注入：调用 import_state(ptr, len) New->>New: 反序列化并重建内部状态 New-->>Host: 返回恢复成功，新模块就绪 Host->>New: 7. 继续推理：延续之前的会话上下文

这个流程的关键在于步骤 2 和步骤 6。旧模块需要把内部状态序列化到一段可迁移的字节序列里；新模块需要能理解这段数据并重建等价的状态。听起来很简单，实际上涉及 Rust 侧的状态导出设计和 JS 侧的编排逻辑。

三、Rust 侧状态导出与 JS 侧编排

3.1 Rust 端：把插件状态序列化为可迁移的字节流

WASM 插件用 Rust 编写时，状态通常散落在多个结构体里——模型配置、会话历史、KV 缓存、甚至正在进行的推理中间结果。需要设计一个统一的导出入口，把所有这些状态打包成一个可序列化的结构。

use serde::{Serialize, Deserialize}; /// 插件内部需要跨版本迁移的状态 #[derive(Serialize, Deserialize)] struct PluginState { /// 插件版本号，用于兼容性检查 version: u32, /// 会话 ID，用于关联前后版本 session_id: String, /// 对话历史：用户和模型的交替消息 messages: Vec<ChatMessage>, /// 模型配置快照：温度、top_p、最大长度等 config: ModelConfig, /// KV 缓存序号偏移量（简化示意，真实场景更复杂） cache_offset: u64, } #[derive(Serialize, Deserialize)] struct ChatMessage { role: String, content: String, } #[derive(Serialize, Deserialize)] struct ModelConfig { temperature: f32, top_p: f32, max_tokens: u32, } /// 把当前状态序列化到线性内存中，返回 (指针, 长度) /// 这一步会被 JS 宿主通过 WASM 导出函数调用 #[no_mangle] pub extern "C" fn export_state() -> *const u8 { // 在实际项目中，state 从全局变量或 OnceCell 中获取 let state = unsafe { &*PLUGIN_STATE.get().unwrap() }; // 用 postcard 做紧凑二进制序列化，比 JSON 更省空间 let bytes = postcard::to_allocvec(state).unwrap(); let len = bytes.len(); // 将数据拷贝到由 JS 分配的缓冲区中 // 此处简化：直接返回指针，实际应使用共享内存 let ptr = bytes.as_ptr(); // 防止 bytes 被释放后指针悬垂 // 实际项目需要把 bytes 存到全局变量或使用 JS 侧分配的缓冲区 std::mem::forget(bytes); ptr } /// 从字节流恢复插件状态 #[no_mangle] pub extern "C" fn import_state(ptr: *const u8, len: usize) -> i32 { let bytes = unsafe { std::slice::from_raw_parts(ptr, len) }; let state: PluginState = match postcard::from_bytes(bytes) { Ok(s) => s, Err(_) => return -1, // 反序列化失败，返回错误码 }; // 版本兼容性检查 if state.version > CURRENT_PLUGIN_VERSION { return -2; // 状态版本比当前插件还新，无法兼容 } // 重建内部状态 unsafe { PLUGIN_STATE = Some(Box::new(state)); } 0 // 成功 } /// 当前插件的状态版本 const CURRENT_PLUGIN_VERSION: u32 = 2; static mut PLUGIN_STATE: Option<Box<PluginState>> = None;

Rust 侧的关键决策：选择postcard而不是serde_json做序列化。postcard是专为no_std和紧凑场景设计的二进制序列化库，生成的字节数组比 JSON 小得多。在 WASM 场景里，每多一个字节都意味着多一次 JS 和 WASM 之间的数据拷贝，所以紧凑序列化对热加载的性能很重要。

3.2 JS 端：编排热加载流程

JS 宿主负责串联整个流程——触发升级、协调状态迁移、加载新模块并传递状态数据。

/** * 热加载 WASM AI 插件：在运行时替换模块并保留会话状态 */ async function hotSwapPlugin(wasmUrl, imports) { // 1. 获取当前插件实例 const oldInstance = window.__pluginInstance; if (!oldInstance) { // 首次加载，直接初始化 window.__pluginInstance = await initPlugin(wasmUrl, imports); return; } // 2. 停用旧模块：等待进行中的推理完成 await oldInstance.exports.pause_inference(); // 3. 导出状态：调用 Rust 侧的 export_state const ptr = oldInstance.exports.export_state(); // 从线性内存中读取长度（约定长度存储在紧接指针的位置） // 实际项目中可以用更规范的 ABI 约定 const memory = oldInstance.exports.memory; const stateBytes = readBytesFromWasm(memory, ptr); // 4. 释放旧模块 oldInstance.exports.deinit(); // 让 Rust 侧释放资源 oldInstance = null; // 5. 加载新模块 const newInstance = await initPlugin(wasmUrl, imports); // 6. 注入状态：将字节数据写回新模块的线性内存 const newMemory = newInstance.exports.memory; const newPtr = writeBytesToWasm(newMemory, stateBytes); const result = newInstance.exports.import_state(newPtr, stateBytes.length); if (result !== 0) { console.error(`状态恢复失败，错误码: ${result}`); // 降级：使用新模块的默认状态重新开始 // 至少比刷新页面好——用户不用重新打开应用 } // 7. 恢复推理 window.__pluginInstance = newInstance; } /** * 从 WASM 线性内存中读取指定长度的字节数组 */ function readBytesFromWasm(memory, ptr) { // ptr 指向数据区，前面 4 字节存长度（一种简单的 ABI 约定） const len = new Uint32Array(memory.buffer, ptr, 1)[0]; const dataOffset = ptr + 4; // 跳过长度前缀 return new Uint8Array(memory.buffer, dataOffset, len); } /** * 将字节数组写入 WASM 线性内存，返回数据指针 */ function writeBytesToWasm(memory, bytes) { // 从内存尾部开始分配，避免与 Rust 侧分配器冲突 // 实际项目应用更严谨的内存管理策略 const memEnd = memory.buffer.byteLength; const ptr = memEnd - bytes.length - 4; new Uint32Array(memory.buffer, ptr, 1)[0] = bytes.length; new Uint8Array(memory.buffer, ptr + 4).set(bytes); return ptr; }

JS 侧的编排逻辑看起来不复杂，但每一步都有需要小心的细节。暂停推理时如果有任务正在执行，不能粗暴终止，需要等待其完成或标记取消点。读写 WASM 线性内存时，指针偏移要对齐约定好的 ABI 布局，否则读到的就是乱码。

四、状态兼容性与内存泄漏，这两个问题绕不开

热加载的原理不难理解，但放到生产环境里，有几个边界情况会暴露出设计中的薄弱环节。

4.1 状态兼容性：新模块读不懂旧状态怎么办

PluginState是一个结构化数据。新版本插件可能增加了字段（比如多加了一个top_k参数）、删除了旧字段、或修改了字段类型。如果新版本直接反序列化旧版本的状态，大概率会失败或者得到错误数据。

应对策略有几种。最简单的是版本标记：PluginState.version字段记录序列化时的插件版本。新模块加载时先检查版本号，如果版本不兼容，可以走降级逻辑——比如只恢复兼容字段（对话历史、session_id），丢弃不兼容的配置项，使用默认值填充新字段。

fn migrate_state(raw: &PluginState) -> PluginState { let mut state = raw.clone(); // 版本 1 没有 top_k 字段，升级时补充默认值 if raw.version < 2 { state.config.top_k = Some(50); // 新增字段给默认值 state.version = 2; } state }

对于跨大版本的升级（比如 v1→v3），一种更稳妥的做法是在插件包中内置多个迁移函数，形成一个迁移链：v1→v2→v3，逐级转换。

4.2 内存泄漏：旧模块释放不干净

WASM 模块被"卸载"时，线性内存会被整体回收。但如果旧模块在 Rust 侧通过wasm_bindgen注册了 JS 闭包、事件监听器或定时器，这些跨边界的引用不会随着模块卸载自动清理。每次热加载，内存占用量会悄悄增长。

解决方法是让每个插件暴露一个deinit()函数，负责清理所有跨边界引用：

#[wasm_bindgen] pub fn deinit() { // 清理定时器 if let Some(handle) = TIMER_HANDLE.take() { handle.cancel(); } // 清理事件监听 EVENT_LISTENERS.with(|listeners| { for listener in listeners.borrow_mut().drain(..) { listener.remove(); } }); // 释放大型堆分配 unsafe { if let Some(state) = PLUGIN_STATE.take() { drop(state); } } }

JS 侧在卸载前必须调用deinit()，然后解除对实例的引用，让 GC 能回收。