扩展安装失败或文件损坏怎么办？

商店扩展已经安装并分配给浏览器账号后，MaskPilot 会在该账号启动时准备需要的扩展文件。下载、文件校验、解压或扩展包结构出现问题时，账号可能在启动前提示扩展安装失败。先保留错误信息并判断失败阶段，不要直接删除浏览器账号或手工修改扩展文件。

先区分是哪一种问题

现象	优先处理
MaskPilot 在账号启动时提示扩展安装失败	进入商店扩展详情页，按下文清除旧安装文件并重新下载
浏览器把扩展标记为损坏	先修复商店扩展的本地安装文件，再检查是否存在浏览器版本兼容问题
扩展显示已停用或不再受支持	不要反复重新下载，按照浏览器更新后的扩展兼容排查处理
扩展只在某一个账号中缺失	确认该账号是否已经选择扩展，并完全关闭后重新启动；参见只在指定账号加载扩展
本地扩展导入失败	本文的清理功能不适用；按本地 Manifest 导入排查步骤检查文件夹或 ZIP

清除商店扩展的旧安装文件

1. 保存网页中的工作，正常关闭所有正在使用该扩展的浏览器账号。
2. 打开 MaskPilot 的扩展页面，进入发生问题的商店扩展详情。
3. 展开“安装遇到问题？”，选择“清除旧安装文件”。
4. 清理完成后，重新启动已经分配该扩展的测试账号。需要的扩展文件会在启动时自动重新下载。
5. 确认账号可以启动，再检查扩展图标、目标网站权限和主要功能。

清除旧安装文件只移除当前设备上的商店扩展副本，不会卸载扩展，也不会改变扩展与浏览器账号的分配关系。不要到客户端数据目录中手工删除文件；这样容易误删其他版本或破坏正在使用的内容。

完整的正常安装和账号分配流程见安装、更新与管理扩展。

重新下载仍然失败

一次只改变一个条件，然后重新启动同一个测试账号：

1. 下载失败：确认当前设备网络稳定，稍后重试，并检查公司网络、安全软件或内容过滤是否阻止了下载。
2. 文件校验或解压失败：再次清除旧安装文件后重试。问题持续出现时不要绕过校验或改用来源不明的副本，应记录扩展名称、版本和错误阶段并联系支持。
3. 找不到有效扩展配置：商店中的当前扩展包可能不完整。不要自行拼接文件；保留扩展名称和版本供支持人员核验。
4. 磁盘写入失败：确认设备有足够可用空间，并检查安全软件是否阻止 MaskPilot 保存应用文件。

Google 的下载错误帮助也建议先检查网络、稍后重试，并留意安全软件造成的下载阻断。这只能用于判断设备环境，MaskPilot 中的修复操作仍应从扩展详情页完成。

重新下载不能解决兼容问题

如果页面明确提示扩展版本与当前浏览器版本不兼容，清除文件不会改变版本范围。应选择兼容的扩展版本，或只在业务允许时调整浏览器版本，并先在测试账号验证。不要修改扩展文件来伪造兼容性。

Chrome 的扩展管理帮助将下载或安装问题、扩展损坏和版本兼容视为不同故障。排查时也应保持这三个阶段分离。

联系支持前记录什么

记录扩展名称和版本、浏览器版本、错误原文、失败发生在下载还是启动阶段、清除旧安装文件的时间，以及同一设备上其他扩展能否正常准备。不要发送账号密码、网站 Cookie、代理凭据或未经脱敏的业务页面截图。