在React开发的Firefox扩展侧边栏中如何访问browser API？

云上老周

2026-9-28

问题根因

这个报错和React本身无关，是你的前端构建工具（ESLint、Webpack/Vite等）在静态检查/编译阶段，没有识别到Firefox扩展运行环境自带的全局browser API，将其判定为未声明变量导致的。

可行解决方案

1. 最简快速方案：显式从window上调用browser API

扩展侧边栏运行在浏览器上下文环境中，browser API默认挂载在window对象下，直接按如下写法调用即可绕过变量未定义报错，无需修改任何构建配置：

// 替换原有的browser.xxx写法
window.browser.runtime.onMessage.addListener((m) => {
  // 处理消息逻辑
});

2. 配置ESLint跳过全局变量检查

如果不想每次都写window.前缀，可以在ESLint配置中声明browser为合法全局变量：

若项目根目录有.eslintrc.json/.eslintrc.js，添加如下配置：

{
  "globals": {
    "browser": "readonly"
  }
}

若未 eject 过Create React App项目，也可以在用到browser API的文件顶部添加注释声明：

/* global browser */

3. 打包工具报错时的配置

如果是Webpack/Vite打包阶段抛出变量未定义错误，需要给打包工具声明browser为外部全局变量：

Webpack配置（webpack.config.js）：

module.exports = {
  // 其他原有配置
  externals: {
    browser: 'global browser'
  }
}

Vite配置（vite.config.js）：

export default defineConfig({
  // 其他原有配置
  define: {
    global: 'window'
  }
})

React适配建议

你可以把扩展API封装为自定义Hook，在组件中使用更便捷，还能自动清理副作用避免内存泄漏，示例如下：

// hooks/useRuntimeMessage.js
import { useEffect } from 'react'

export const useRuntimeMessage = (callback) => {
  useEffect(() => {
    const listener = (msg) => callback(msg)
    browser.runtime.onMessage.addListener(listener)
    // 组件卸载时自动移除监听器
    return () => browser.runtime.onMessage.removeListener(listener)
  }, [callback])
}

在组件中直接调用即可：

const FormComponent = () => {
  const [inputValue, setInputValue] = useState('')
  useRuntimeMessage((msg) => {
    // 接收content script发送的选中文本
    if (msg.type === 'TEXT_SELECTED') {
      setInputValue(msg.content)
    }
  })
  return <input value={inputValue} onChange={e => setInputValue(e.target.value)} />
}

你之前尝试的将browser作为prop传入组件的方案也完全可行，只需在入口文件将window.browser作为prop传入根组件即可。

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