本地扩展 Manifest 导入失败

本地扩展在出现确认页面前导入失败，通常表示 MaskPilot 无法识别唯一有效的扩展根目录，或无法验证其中的 manifest.json。这与商店扩展在账号启动时下载失败不同，清除商店扩展安装文件不能修复本地导入问题。

按提示检查扩展包

现象	检查内容
不支持来源格式	选择扩展根文件夹或 ZIP 包。本地导入不接受 CRX 包。
找不到 Manifest	文件夹中的 manifest.json 必须直接位于所选目录；ZIP 可以放在包根目录，或放在一个可识别的外层目录内。
检测到多个本地扩展	ZIP 中存在多个类似扩展根目录的文件夹。拆成独立包，每次只导入一个扩展。
ZIP 无法打开	从可信来源重新下载或构建扩展包，不要绕过包检查，也不要混入其他版本的文件。
Manifest 无效或不受支持	确认文件是有效 JSON，使用 manifest_version: 3，并包含有效名称和版本。
最低浏览器版本无效	使用扩展开发者提供的有效浏览器版本值，不要为了通过导入而直接删除版本要求。

MaskPilot 还会验证扩展声明的浏览器能力和网站访问项。若提示指向这些声明，应与开发者提供的原始 Manifest V3 扩展包对照，不要自行编造权限名称或域名匹配规则。

检查文件夹或 ZIP 层级

使用文件夹导入时，应选择直接包含 manifest.json 的目录，而不是它的上级代码仓库或下载目录。

ZIP 导入可以使用以下结构：

extension.zip
├── manifest.json
├── background.js
└── icons/

或者：

extension.zip
└── extension-release/
    ├── manifest.json
    ├── background.js
    └── icons/

不要把多个扩展版本或多个分别包含 Manifest 的目录放入同一个 ZIP。移除操作系统快捷方式和符号链接，使用可信来源提供的普通文件重新打包。

不降低安全要求地检查 Manifest

1. 使用文本编辑器打开 manifest.json，确认它是 JSON 而不是 JavaScript 文件；JSON 不允许注释或末尾多余逗号。
2. 确认 manifest_version 的值是数字 3。
3. 确认 name 存在并能解析为可读文本；使用本地化名称时，还需要对应的本地化文件。
4. 确认 version 使用浏览器扩展版本格式，而不是 latest、beta 等标签。
5. 如果存在 minimum_chrome_version，保留开发者给出的有效版本要求，随后为账号选择兼容的浏览器版本。
6. 权限或网站访问声明曾被修改或损坏时，从可信原始包恢复，不要凭猜测填写。

官方的 Manifest 格式说明同样要求扩展根目录包含 manifest.json，并将 Manifest V3、名称和版本列为核心字段。扩展调试指南也说明必填字段无效会阻止 Manifest 加载。

使用干净的扩展包重试

1. 若来源或完整性不确定，保留失败包作为排查证据，不要继续修改。
2. 从同一可信开发者获取新的文件夹或 ZIP，或按项目文档重新构建正式输出目录。
3. 重新导入，并在确认页面核对名称、版本、浏览器要求、网站访问范围和浏览器能力。
4. 选择较窄的适用范围，先在一次性测试账号验证，再扩大使用范围。

正常导入流程和仅限当前设备的边界见导入本地浏览器扩展。若导入成功后账号启动才提示浏览器版本冲突，应改用扩展兼容性排查步骤。

MaskPilot 导入时不会证明什么

通过导入检查不代表第三方代码安全，也不证明所有被引用的脚本、图标和网站流程都能正常运行。该检查只验证本地管理所需的扩展包与 Manifest 信息。只导入来源和用途可信的内容，并在不暴露生产凭据的条件下测试行为。

联系支持前，记录来源类型、扩展包名称、manifest.json 是否位于所选根目录、完整可见错误，以及目标账号的浏览器版本。除非支持人员明确需要经过最小化处理的样本，否则不要提交源代码、凭据、令牌、私有域名或无关业务数据。