Chrome扩展商店安装后Popup空白问题求助

问题背景 #

我把一款Chrome扩展上传到Chrome商店并通过了审核，但从商店安装后，扩展的Popup只显示一个小型空白框。怀疑是文件上传方式导致的问题，上传时我将build文件夹、manifest.json和tasks.png压缩成ZIP文件提交。附上我的manifest.json代码：

{
  "manifest_version": 3,
  "name": "Reminder-App",
  "version": "0.3.0",
  "description": "Reminder app for all your tasks",
  "icons": {
    "128": "tasks.png"
  },
  "action": {
    "default_popup": "./build/index.html",
    "default_title": "Reminder App",
    "default_icon": {
      "16": "tasks.png",
      "24": "tasks.png",
      "32": "tasks.png"
    }
  },
  "permissions": ["storage"]
}

具体排查步骤 #

• 核对打包结构与文件路径

  • 确认ZIP包的根目录直接包含manifest.json、build文件夹和tasks.png，不能把这些文件嵌套在同一个子文件夹里——Chrome会以根目录的manifest为入口找资源，嵌套结构会导致找不到Popup文件。
  • 检查default_popup的路径准确性：当前配置是./build/index.html，需保证ZIP解压后，根目录下的build文件夹内确实存在index.html，且文件名大小写完全匹配（Chrome对路径大小写敏感）。

• 本地复现并排查加载错误

  • 本地加载扩展测试：打开Chrome的chrome://extensions/页面，开启开发者模式，选择“加载已解压的扩展程序”，选中包含manifest和build文件夹的目录，观察Popup是否正常显示。如果本地正常，说明是打包或商店上传过程中出现了文件损坏/路径错误；如果本地也显示空白，直接排查index.html的资源引用问题。
  • 查看控制台报错：右键点击空白Popup选择“检查”，打开开发者工具的Console面板，查看是否存在资源加载失败（如JS、CSS文件404）、语法错误，或者CSP（内容安全策略）拦截提示——Manifest V3对CSP要求严格，内联脚本、未授权的外部资源都会被拦截，导致页面空白。

• 验证资源文件完整性

  • 确认tasks.png未损坏且路径匹配：比如icons字段里的128指向根目录的tasks.png，需保证文件确实在根目录，且格式为Chrome支持的类型（PNG、ICO均可）。
  • 检查build文件夹的编译产物：如果是用React、Vue等框架编译生成的build文件夹，需确认编译过程未遗漏资源，且所有相对路径引用正确。

• 检查Manifest配置细节

  • 确认Manifest V3配置合规：action字段是V3的正确写法（替代了旧版的browser_action），当前这部分配置没问题，但要确保没有其他V3不兼容的字段。
  • 补全CSP配置（若有需要）：如果扩展需要加载外部资源或使用内联脚本，需在manifest中添加content_security_policy字段，比如允许本地脚本的基础配置："content_security_policy": { "extension_pages": "script-src 'self'; object-src 'none'" }，可根据实际需求调整规则。

内容的提问来源于stack exchange，提问作者Michael Horvilleur