OpenCV.js 的难点往往不在调用 cv.inpaint 或 cv.GaussianBlur，而在于让 JavaScript 胶水代码、WebAssembly 二进制和静态服务器的路径规则在生产环境中保持一致。LemonArt 将 OpenCV.js 作为静态资源发布，并在运行时确认模块是否就绪，从而避免开发服务器的路径容错掩盖部署问题。
一、OpenCV.js 实际上是两个资源
很多部署故障源于把 OpenCV.js 当成单一 JavaScript 文件。常见构建产物由 JavaScript 胶水代码和 .wasm 二进制组成，胶水代码会根据自身位置推断 WASM 路径。如果文件被打包、重命名或移动到与预期不同的目录，浏览器就可能得到 404，最终表现为 cv 未定义、运行时一直 loading 或算法按钮点击无响应。
LemonArt 把 OpenCV 相关静态文件放在 public/opencv 目录，生产构建后保持稳定的绝对访问路径。这样 Vite 不会把 WASM 当成普通业务模块重新改写，Cloudflare Pages 也能直接通过静态文件服务它。
- 胶水脚本必须返回 200，并且内容不是 HTML 错误页。
- WASM 文件必须能通过稳定路径访问，响应类型和缓存策略要合理。
- 跨域部署时需要确认 COOP、COEP 和资源来源是否满足 WebAssembly 使用条件。
- 不要只验证本地 dev server，要用最终 dist 目录启动静态服务器复测。
二、按需加载比首屏强制加载更合适
图片格式转换、压缩和基础裁剪不一定需要 OpenCV.js。如果首屏就加载数 MB 的 WebAssembly 文件，会增加移动网络下的首屏成本。LemonArt 在进入预处理或修复流程时才请求 OpenCV.js，同时用 Promise 缓存加载过程，多个控件同时触发时也只会创建一个加载任务。
let runtimePromise: Promise<OpenCvRuntime> | null = null
export function loadOpenCv() {
if (!runtimePromise) runtimePromise = loadScript('/opencv/opencv.js')
.then(() => waitForModuleReady())
return runtimePromise
}ts三、SIMD 不是一个可以盲信的开关
SIMD 能让部分 WebAssembly 运算使用向量指令，但浏览器、设备和构建版本都可能影响最终能力。正确做法是区分“浏览器支持 SIMD”和“当前 OpenCV 构建启用了 SIMD”两件事：前者是能力检测，后者是运行时标识或构建产物信息。界面可以展示 SIMD、WASM 或加载中，但算法逻辑不应依赖一个未经验证的布尔值。
LemonArt 的探测分成三步：先用 WebAssembly.validate 验证一段最小的 SIMD 指令流，确认运行时支持向量指令；再对 /opencv-simd/opencv.js 发 HEAD 请求，排除静态服务器把缺失路径回退成 HTML 错误页的情况；最后读取 cv.getBuildInformation()，用正则匹配 wasm_simd128 等构建标识，得到 simdBuild 与 simdSupported 两个独立布尔值。
当 SIMD 不可用时，LemonArt 仍然回退到普通 WASM 路径。功能正确性优先于单一设备上的峰值性能，尤其是图像修复这种用户更关心结果稳定性的功能。
function canUseWasmSimd() {
if (typeof WebAssembly === 'undefined') return false
try {
return WebAssembly.validate(new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 4, 1, 96, 0, 0,
3, 2, 1, 0, 10, 10, 1, 8, 0, 253, 12, 0, 0, 11]))
} catch { return false }
}
const simdCv = await probeSimdAsset() // HEAD /opencv-simd/opencv.js，排除 HTML 错误页
const simdBuild = /-msimd128|wasm_simd128|WASM_SIMD/i.test(String(cv.getBuildInformation()))ts四、生产环境排查清单
遇到线上 OpenCV.js 无法工作时，建议按网络层、脚本层、模块层和算法层逐层排查，而不是直接替换一段调用代码。
- Network：检查 /opencv/opencv.js 和对应 .wasm 是否都是 200。
- Script：确认脚本没有被 HTML fallback、CSP 或 MIME 错误拦截。
- Runtime：等待 Module.onRuntimeInitialized 或等价就绪信号后再创建 Mat。
- Algorithm：给 cv.imread、cv.inpaint 等关键步骤加错误边界和 Mat 释放。
- Deployment：用 wrangler pages deploy dist 发布后，直接访问线上静态资源验证。
五、缓存与版本更新
WASM 文件适合长期缓存，但缓存也会让版本更新变得隐蔽。发布新版本时要保证胶水脚本和 WASM 来自同一构建，必要时通过文件名或构建目录生成版本标识。Cloudflare Pages 的静态资源缓存可以降低重复下载，但不能替代版本一致性检查。
LemonArt 在脚本 URL 上附加构建版本查询参数（如 /opencv/opencv.js?v=5.0.0-release.1），与 Vite 的产物哈希互补：版本号变化时浏览器会重新拉取资源，而版本号不变时则可以放心使用长期缓存。普通构建与 SIMD 构建使用两套独立路径，避免回退逻辑互相覆盖。
六、初始化超时、中止与运行时解析
胶水代码返回的对象不一定是可直接使用的运行时：它可能是未初始化的 Module，也可能是一个需要再调用一次的工厂函数。LemonArt 在解析链中依次处理 Promise、工厂函数和 Module 三种形态，最后挂接 onRuntimeInitialized 与 onAbort 回调，并设置 60 秒初始化超时。任何一步失败都会让加载 Promise 以明确错误结束，而不是让页面停留在永久的“加载中”。
加载过程本身也会被缓存：无论脚本标签、Promise 还是运行时解析，都复用同一个模块级变量，多个控件同时进入修复流程时只产生一次网络请求。脚本用 data-lemonart-opencv 标记去重，重复调用不会插入第二个 script 标签。
const timeout = setTimeout(() => reject(new Error('OpenCV.js initialization timed out')), 60000)
cv.onRuntimeInitialized = () => { clearTimeout(timeout); resolve(cv) }
cv.onAbort = (error) => { clearTimeout(timeout); reject(error) }
let runtimePromise: Promise<OpenCvRuntime> | undefined
function load() {
if (!runtimePromise) runtimePromise = loadOpenCvModule()
return runtimePromise
}ts要点总结
- 把 OpenCV.js 与 WASM 作为可验证的静态资源发布。
- 按需加载并缓存 Promise，减少首屏成本和重复初始化。
- SIMD 能力要拆成“运行时支持”与“构建启用”两个布尔值分别验证。
- 初始化必须带超时与 onAbort 处理，失败要可诊断而不是永远加载。
- 线上排查必须包含最终域名下的静态资源和模块就绪状态。