Transformers.js 跨域存储：模型缓存怎么排查

先整理环境与来源

先不要急着修改缓存代码。把页面来源、模型来源、浏览器版本、是否使用私密窗口、是否允许站点数据以及当前部署方式记录下来。模型文件、用户图片和推理结果应分开描述，避免把“模型已缓存”误认为“用户数据也会被保存”。

如果还没有浏览器端视觉推理流程，可以先参考浏览器端视觉推理的图片分类流程，再把模型缓存单独作为一个测试环节。

设计存储策略

把存储目标拆成三层：模型缓存、应用配置和用户数据。模型缓存的目标是减少重复下载；应用配置只保存必要的版本或状态；用户图片和推理结果则应根据产品需求决定是否持久化。不要为了让模型复用，就默认保存原始图片。

1. 列出页面来源与模型来源，确认它们是否属于同一来源，以及浏览器是否把它们视为可共享的存储边界。
2. 为模型来源、模型版本、运行后端和应用版本建立可读的缓存记录。版本变化时，优先让新旧资源能够区分。
3. 为失败情况设计降级路径：无法使用跨来源存储时，允许重新下载、提示用户，或切换到已确认的本地资源。
4. 把清理动作写进测试计划，包括清除站点数据、切换模型版本、退出私密窗口和重新打开页面。

接入模型加载流程

接入时建议把“检查环境”“加载模型”“记录结果”“执行推理”分成四个函数或模块。加载流程只负责返回成功、失败、是否复用已有缓存等状态，不要把图片内容写入模型缓存记录。

1. 页面启动后先检测当前浏览器条件，并记录测试编号，不要立即开始大文件下载。
2. 确认模型来源和版本后发起加载请求。将开始时间、结束时间、结果状态和错误类别写入开发日志。
3. 首次加载完成后执行一次最小推理，只使用已获授权的测试图片。
4. 关闭页面并重新打开，再次加载同一模型，比较网络请求、加载时间和推理是否正常。
5. 切换到另一个模型版本重复测试，确认旧缓存不会被误当成新版本。

用一个小案例复查

假设你正在开发一个浏览器端图片分类工具。准备一张不含个人信息的测试图片，固定页面来源、模型版本和浏览器条件。

1. 第一次访问时记录模型请求是否完成，以及页面是否能正常推理。
2. 刷新页面，观察是否仍然发起完整下载，并记录缓存复用的证据。
3. 关闭浏览器后重新打开页面，验证结果是否与刷新测试一致。
4. 清除站点数据后再次访问，确认应用能够识别缓存不存在并给出清楚提示。
5. 改用一张含敏感信息的模拟图片，确认应用不会把原图、缩略图或推理文本写入模型缓存记录。

常见故障与修正

• 每次访问都重复下载。原因可能是当前浏览器不支持所需能力、存储被清除、来源组合变化，或缓存版本键不一致。修正时先固定页面和模型来源，再检查站点数据状态，最后对比版本记录。
• 加载请求被浏览器拒绝。原因可能是资源响应、来源策略或浏览器限制不满足条件。修正时查看开发者工具中的网络和存储错误，确认资源服务端配置与当前浏览器支持情况，不要只靠重试。
• 普通窗口成功，私密窗口失败。原因可能是两种窗口的持久化条件不同。修正时把私密窗口作为不保证持久缓存的独立场景，并提供重新加载或明确提示。
• 模型加载成功但推理失败。原因可能是运行后端、模型版本或输入格式不匹配。修正时先用固定小样本复现，再分别替换模型、后端和输入，避免同时改动多个变量。
• 清除数据后仍显示旧状态。原因可能是应用自己的状态记录没有同步清理。修正时同时清理应用状态、模型缓存和测试日志，并重新打开页面确认状态来源。

发布前隐私验收

发布前至少完成下面的检查，并保留浏览器、页面来源、模型版本和测试时间。

• 确认模型来源、页面来源和版本记录完整。
• 确认首次加载、刷新访问、关闭重开和清除数据后的行为均有记录。
• 确认模型缓存记录不包含原始图片、用户输入、推理结果或可识别个人信息。
• 确认跨来源存储不可用时有可理解的提示和可执行的降级路径。
• 确认普通窗口与私密窗口的差异已写入产品说明或测试记录。
• 确认更换模型版本后不会复用错误资源。
• 确认开发日志不会输出敏感输入、完整图片内容或不必要的来源凭据。
• 确认隐私清理、站点数据清理和缓存失效测试可以重复执行。