Manifest V3 Chrome扩展报错：Cannot read properties of undefined (reading 'setPopup')

核心错误原因 #

Uncaught TypeError: Cannot read properties of undefined (reading 'setPopup') 本质是调用setPopup的对象不存在。Manifest V3 对扩展API做了关键调整，直接导致旧版V2的写法失效：

• 移除chrome.browserAction/chrome.pageAction，统一替换为chrome.action
• 背景脚本改为Service Worker，API调用时机与上下文限制更严格

分步修复方案 #

1. 替换旧版API调用对象 #

将代码中所有chrome.browserAction.setPopup或chrome.pageAction.setPopup替换为chrome.action.setPopup：

// 错误（V2写法）
chrome.browserAction.setPopup({popup: 'popup.html'});
// 正确（V3写法）
chrome.action.setPopup({popup: 'popup.html'});

2. 修正Manifest配置 #

在manifest.json中，用action字段替代旧版的browser_action：

{
  "manifest_version": 3,
  "name": "你的扩展名称",
  "version": "1.0",
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "background": {
    "service_worker": "background.js"
  }
}

3. 调整Service Worker中的调用时机 #

背景脚本作为Service Worker，不能在全局直接执行API调用，需绑定到合适的事件触发：

// background.js 示例
chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setPopup({popup: 'popup.html'});
});

// 针对特定标签页设置弹窗
chrome.tabs.onActivated.addListener((activeInfo) => {
  chrome.action.setPopup({
    popup: 'tab-specific-popup.html',
    tabId: activeInfo.tabId
  });
});

4. 规范Popup页面的API调用 #

在Popup.js中，需确保在DOM加载完成后调用API，避免上下文未初始化：

// Popup.js 示例
document.addEventListener('DOMContentLoaded', () => {
  chrome.action.setPopup({popup: 'updated-popup.html'});
});

5. 调试与权限检查 #

• 开启扩展开发者模式，通过“检查视图”查看Service Worker控制台日志，确认API调用上下文
• 若需针对特定标签页设置弹窗，需在manifest.json中声明tabs权限：

{
  "permissions": ["tabs"]
}

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