Chrome扩展开发chrome.storage.sync.set报错及加载问题排查

1. chrome.storage.sync.set 调用报错修复 #

报错触发原因 #

控制台抛出Cannot read properties of undefined (reading 'sync')的核心原因只有两类：

• 未在扩展配置文件中声明storage权限：Chrome扩展所有敏感API都需要在manifest.json中显式声明权限后才会注入运行上下文，未声明时chrome.storage对象本身为undefined，自然无法读取sync属性
• 调用上下文错误：chrome.storage属于扩展专属API，如果将调用逻辑写在普通网页脚本、未配置隔离世界的注入脚本中，会无法获取完整的Chrome扩展API对象

修复步骤 #

1. 打开项目根目录下的manifest.json，在permissions数组中添加"storage"权限，做图片下载功能建议同时加上下载相关权限，参考配置：

{
  "manifest_version": 3,
  "name": "图片快速下载扩展",
  "version": "1.0",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": ["storage", "downloads", "activeTab"],
  "background": {
    "service_worker": "background.js"
  }
}

2. 检查代码位置：弹窗逻辑必须放在popup.html引入的脚本中，若需要在页面注入脚本中操作存储，需要通过runtime消息通信传递给后台脚本处理，不要直接在content script里未做配置就调用storage API
3. 修改配置后必须到Chrome扩展管理页重新加载扩展，避免旧配置缓存导致修改不生效

2. 本地开发扩展加载异常修复 #

正确加载流程 #

1. 打开Chrome浏览器，地址栏输入chrome://extensions/回车进入扩展管理页
2. 打开页面右上角的开发者模式开关，未开启该模式时无法加载本地未打包的开发版扩展，这是最常见的加载失败原因
3. 点击页面左上角的「加载已解压的扩展程序」按钮，在文件选择弹窗中选中manifest.json所在的项目根目录，不要选中内层子文件夹、也不要直接点选manifest.json文件，确认后即可完成加载

常见报错排查 #

• 提示「清单文件缺失或不可读取」：确认选择的目录是否正确，必须定位到存放manifest.json的最外层项目文件夹
• 提示清单字段错误：对照Manifest V3规范检查字段格式，V3版本已废弃V2的background.scripts等字段，需替换为background.service_worker
• 加载后功能不符合预期：点击扩展卡片上的「重新加载」按钮刷新扩展，清除旧脚本缓存后再测试

相关报错截图 #

#

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