浏览器扩展中的 WASM：MV3 约束、CSP 与生命周期实践

┌─ 浏览器扩展 ─────────────────────────────────┐
│ Service Worker(可回收) │ Popup/Options(有 DOM) │
│        ▲               │                      │
│        └──── 消息 ──────┘                      │
│ Content Script(注入页面, JS 环境隔离)          │
└──────────────────────────────────────────────┘
WASM 可跑在任何一块，但三者 CSP、生命周期、可用 API 各不相同。

四个核心约束：
  1. CSP 默认禁止动态代码生成 → WASM 编译可能被拦
  2. Service Worker 空闲约 30 秒被回收 → 内存中的 WASM 实例随之消失
  3. 内容脚本的 CSP 受宿主页面影响 → 同一模块在不同站点表现不同
  4. 各浏览器对 wasm-unsafe-eval 的支持程度不一致

典型报错：
  CompileError: WebAssembly.instantiate(): Wasm code generation
  disallowed by Content Security Policy.
原因：WASM 编译被视为「动态代码生成」，被 MV3 默认 CSP 拦截。
解决：在 manifest 的 content_security_policy 里显式允许。

{
  "manifest_version": 3,
  "content_security_policy": {
    "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'"
  }
}

要点：
  'wasm-unsafe-eval' 只放开 WASM 编译，不放行 eval / new Function
  比 'unsafe-eval' 安全得多，是 MV3 推荐的写法
  extension_pages 管 service worker 与扩展页面；
  content script 的 CSP 由宿主页面决定，不受 extension_pages 控制

若模块用了 SharedArrayBuffer / 多线程：
  需要 COOP/COEP，扩展页面可在 manifest 里配 cross_origin_embedder_policy
  但内容脚本场景基本无法满足，多线程 WASM 只适合放扩展页面

若同时要用远程 fetch 的 wasm（不推荐）：
  还需在 CSP 里加 connect-src，并承担商店审核风险
  绝大多数场景应把 wasm 打进包体，避免运行时下载

MV3 service worker 的生命周期：
  事件到来 → 唤醒（冷启动，跑 top-level 代码）→ 处理事件
  → 空闲约 30 秒 → 被终止，全局状态全部丢失
含义：WASM 实例、编译好的 Module、缓存的结果，全都不能假设常驻。

// 反例：把实例存在全局，指望它一直在
let instance;                     // SW 回收后变成 undefined
self.addEventListener('install', async () => {
  instance = await loadWasm();    // 下次唤醒时这个实例已经没了
});

// 正例：每次事件处理时惰性加载，用编译缓存减少重复成本
let modulePromise = null;
async function getInstance() {
  modulePromise ??= WebAssembly.compileStreaming(fetch(chrome.runtime.getURL('app.wasm')));
  return WebAssembly.instantiate(await modulePromise, imports);
}

三处可持久化的位置：
  chrome.storage.local  存小状态（配置、进度），异步 API
  IndexedDB             存大块数据（模型权重、缓存结果）
  Cache API             存编译前的字节，配合引擎编译缓存
原则：内存里只放「可重建」的东西，一切重要状态立即落盘。

{
  "manifest_version": 3,
  "web_accessible_resources": [
    {
      "resources": ["app.wasm", "app.js"],
      "matches": ["<all_urls>"]
    }
  ]
}

web_accessible_resources 的作用：
  允许内容脚本或页面通过 chrome.runtime.getURL() 访问扩展内文件
  若要在内容脚本里 fetch 扩展内的 wasm，必须在这里声明，否则 404
注意：暴露给 <all_urls> 会带来指纹识别风险，尽量收窄 matches。

打包要点：
  1. wasm 与 js glue 一并放进扩展包，不要依赖运行时下载
  2. 保留 application/wasm 的类型信息（部分构建链会丢失）
  3. 用 bundler 时确保 wasm 以 asset 形式产出，路径可被 getURL 解析
  4. 商店审核对包体有上限（Chrome 单包约 2 GB，实际越小越好）

// 从扩展内部加载 wasm（相对路径会解析到扩展根）
const url = chrome.runtime.getURL('app.wasm');
const { instance } = await WebAssembly.instantiateStreaming(fetch(url), imports);

// SW 侧：处理来自 popup / content script 的请求
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'compute') {
    runWasm(msg.payload).then((out) => sendResponse({ ok: true, out }));
    return true;               // 关键：返回 true 才能异步 sendResponse
  }
});

消息传递的两个硬约束：
  1. 结构化克隆：只能传可克隆对象（ArrayBuffer 可，TypedArray 可，函数不可）
  2. 大数组优先传 ArrayBuffer 而非 JSON 数组，避免逐元素序列化
传 WASM 计算结果时：直接在扩展页面侧把结果写成 ArrayBuffer 传出，
                   接收侧建 TypedArray 视图，一次拷贝即可。

版本兼容注意：
  不同浏览器对结构化克隆的支持边界略有差异
  复杂对象优先序列化成 ArrayBuffer 再传，兼容性最稳

内容脚本里的 WASM 受两重 CSP 影响：
  扩展侧：web_accessible_resources 是否放行该文件
  页面侧：宿主页面的 CSP 是否允许 wasm 编译
结论：在严格 CSP 的页面上（如部分银行、邮箱站点），内容脚本可能无法编译 WASM。

// 稳健做法：把计算放回扩展页面 / service worker，内容脚本只做 DOM 交互
// content script:
const result = await chrome.runtime.sendMessage({ type: 'compute', payload });
renderResult(result);

两种注入方式：
  content script（默认）  与页面共享 DOM，但 JS 环境隔离，互不可见
  注入到页面主世界       通过 script 标签注入，可与页面 JS 交互但失去隔离
安全建议：需要访问页面 JS 变量时才注入主世界，且只传数据不传逻辑；
          WASM 计算尽量留在隔离环境，避免与页面脚本互相污染。

扩展里 WASM 的额外成本：
  每次 service worker 冷启动都要重新实例化（编译可缓存，实例化不可）
  popup 每次打开都是一个新页面上下文，同样要实例化
缓解：把重计算移到常驻性更好的 offscreen document 或独立标签页。

内存三档参考：
  service worker   通常几十 MB，超了会被回收或崩溃
  popup            与普通标签页接近，但用户关闭即释放
  offscreen        可申请更多，适合长任务
移动端扩展（Firefox Android / Safari iOS）内存更紧，务必按最小可用设计。

offscreen document 的定位：
  需要 DOM 或长驻状态时，用 chrome.offscreen 创建一个隐藏页面
  它不会随 popup 关闭而消失，适合承载 WASM 实例与长任务
  代价是更显眼的内存占用，要显式管理其生命周期。

主要差异点：
  1. Firefox 的 MV3 仍保留 background scripts 的部分语义
  2. Safari 的扩展由 Xcode 打包，CSP 与资源访问更严格
  3. 三者的 service worker 回收策略不同，不能假设统一超时
对策：把生命周期相关逻辑写成「随时可重建」，不做任何常驻假设。

[ ] 用 webextension-polyfill 统一 API 差异
[ ] 不依赖任何「实例常驻内存」的假设
[ ] 对 WASM 加载失败做兜底（回退到纯 JS 实现或提示）
[ ] 每个浏览器单独跑一遍加载与冷启动测试

调试入口：
  chrome://extensions → 开启开发者模式 → service worker 有独立 DevTools
  WASM 源码级调试需要 DWARF 段 + 浏览器 DevTools 支持
  发布版剥离 DWARF（体积），开发版保留
常见问题定位：
  编译失败先看 CSP 报错；404 先看 web_accessible_resources
  实例化失败先看 import 是否齐全（SW 环境缺 DOM API）

发布检查：
  1. 剥离调试符号与 sourceMappingURL，压缩 wasm
  2. 收窄 web_accessible_resources 的 matches
  3. 商店审核关注「是否下载并执行远程代码」→ 本地打包可避免
  4. 声明数据用途，若 WASM 处理用户数据需在隐私政策中说明

[ ] manifest 配 'wasm-unsafe-eval'，未使用 'unsafe-eval'
[ ] wasm 与 glue 随包发布，web_accessible_resources 收窄
[ ] 不在全局变量里缓存 WASM 实例，改为事件内惰性创建
[ ] 重要状态写 storage / IndexedDB，内存只放可重建数据
[ ] 消息异步响应 return true，大数组传 ArrayBuffer
[ ] 内容脚本不直接实例化 WASM，计算回扩展页面
[ ] 三浏览器各跑一遍冷启动与加载失败兜底
[ ] 发布版剥离 DWARF 与 sourcemap

推荐分层：
  内容脚本   只做 DOM 读取与渲染，不碰 WASM
  扩展页面   UI 与 WASM 实例（popup / options / offscreen）
  SW         调度与消息中转，尽量无状态
这样每一层都能独立重建，生命周期回收不会导致功能不可用。