Chrome Web Store安装自研扩展报错：Download error: Could not unzip extension

一、排查打包过程的潜在问题 #

• 验证zip包完整性：
  手动解压本地生成的dist.zip，确认所有文件都能正常解压无损坏。vite build刚完成就执行zip命令可能因文件未完全写入导致打包不完整，可在zip前加延迟：sleep 2 && zip dist.zip -r dist。
• 修正zip路径结构：
  Chrome扩展要求zip包根目录直接包含manifest.json，不能嵌套在dist/子目录下。若当前解压后是dist/manifest.json，修改打包命令为cd dist && zip ../dist.zip -r .。
• 更换打包工具：
  系统自带zip命令可能存在兼容性bug，换成7z或Node.js的archiver库打包。比如修改package.json脚本：

  "build:zip": "7z a -tzip dist.zip ./dist/*"
  

二、排查构建产物的问题 #

• 检查包大小与文件数量：
  Chrome Web Store扩展包最大限制为100MB，接近或超过该值可能触发解压失败。同时过多小文件也可能引发异常，尝试合并静态资源（如小CSS/JS文件）。
• 清理特殊文件名：
  确保dist目录下无中文、空格、非ASCII等特殊字符的文件名，这类文件可能导致商店端解压工具处理异常。
• 校验manifest合法性：
  用Chrome「扩展程序」页面的「打包扩展程序」功能重新打包，Chrome会自动校验manifest.json格式，生成的crx包可直接测试安装，间接验证zip包有效性。

三、商店与本地环境排查 #

• 确保版本号一致：
  检查manifest.json中的version字段与npm version patch更新的版本号完全匹配，版本号不匹配可能导致商店解析异常。
• 清理Chrome缓存：
  本地缓存可能残留损坏的旧安装包，尝试清除浏览器缓存后用隐身窗口测试安装。
• 重新生成完整包：
  每次提交前删除dist目录和dist.zip，重新执行构建打包脚本，避免旧文件残留导致异常。

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