如何在Chrome扩展的content.js中正确注入React

我之前在开发Chrome扩展时也踩过这个坑——在content script里用React确实有不少需要注意的细节，毕竟content script的执行上下文和页面本身是隔离的，直接上手很容易出问题。下面分享几个我亲测有效的解决方案，以及常见错误的排查思路：

方法一：手动注入React与组件脚本 #

这种方法适合快速验证或者小型组件，核心思路是先在页面上下文注入React和ReactDOM，再注入你的React组件代码（因为content script不能直接import npm包，且和页面全局上下文隔离）。

步骤1：编写content.js负责注入脚本 #

// content.js
// 封装一个注入脚本的工具函数
function injectScript(src) {
  return new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = src;
    script.onload = resolve;
    script.onerror = reject;
    // 注入到页面的<head>中，运行在页面全局上下文
    document.head.appendChild(script);
  });
}

// 加载React并注入组件
async function initReactApp() {
  try {
    // 可选：用本地打包好的React文件（推荐生产环境用这个）
    // const reactUrl = chrome.runtime.getURL('react.production.min.js');
    // const reactDomUrl = chrome.runtime.getURL('react-dom.production.min.js');
    
    // 或者用CDN快速测试
    await injectScript('https://unpkg.com/react@18/umd/react.production.min.js');
    await injectScript('https://unpkg.com/react-dom@18/umd/react-dom.production.min.js');
    
    // 注入你的React组件脚本
    await injectScript(chrome.runtime.getURL('my-react-component.js'));
    console.log('React组件注入成功');
  } catch (error) {
    console.error('加载/注入失败:', error);
  }
}

initReactApp();

步骤2：编写你的React组件脚本 #

注意这个脚本会运行在页面全局上下文，所以要直接使用全局的React和ReactDOM对象：

// my-react-component.js
// 从全局上下文获取ReactDOM的createRoot
const { createRoot } = window.ReactDOM;

// 创建一个挂载容器并添加到页面
const appContainer = document.createElement('div');
appContainer.id = 'my-chrome-ext-react-app';
// 可以给容器加样式避免和页面元素冲突
appContainer.style.position = 'fixed';
appContainer.style.top = '20px';
appContainer.style.right = '20px';
appContainer.style.zIndex = '9999';
document.body.appendChild(appContainer);

// 你的React组件（支持JSX，不过如果没转译的话要手动写React.createElement）
// 建议用构建工具转译JSX，不然写起来很麻烦
function MyExtensionComponent() {
  return window.React.createElement('div', { className: 'ext-component' }, [
    window.React.createElement('h3', null, '我是Content Script里的React组件'),
    window.React.createElement('p', null, '终于成功渲染啦！')
  ]);
}

// 渲染组件
const root = createRoot(appContainer);
root.render(window.React.createElement(MyExtensionComponent));

步骤3：配置manifest.json #

必须把注入的脚本声明为web_accessible_resources，否则Chrome会阻止content script访问这些资源：

{
  "manifest_version": 3, // 如果你用v2的话语法略有不同
  "name": "React in Content Script Demo",
  "version": "1.0",
  "content_scripts": [
    {
      "matches": ["<all_urls>"], // 替换成你需要注入的网站
      "js": ["content.js"]
    }
  ],
  "web_accessible_resources": [
    {
      "resources": ["my-react-component.js", "react.production.min.js", "react-dom.production.min.js"],
      "matches": ["<all_urls>"]
    }
  ]
}

方法二：用构建工具（Vite/Webpack）打包成独立脚本 #

如果你的组件比较复杂，需要写JSX、用hooks或者其他npm包，手动写React.createElement太折磨人，推荐用构建工具把React组件打包成自执行的IIFE脚本，再用content.js注入。

以Vite为例：

1. 创建一个React项目，配置vite.config.js，把打包格式设为IIFE：

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: './src/main.jsx',
      name: 'MyExtensionReactApp',
      formats: ['iife'],
      fileName: () => 'my-react-component.js'
    },
    rollupOptions: {
      // 把React和ReactDOM打包进脚本，避免依赖全局变量
      external: [],
      output: {
        globals: {}
      }
    }
  }
});

2. 正常写你的React组件（比如src/App.jsx），然后在src/main.jsx里直接渲染组件到页面：

// src/main.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.createElement('div');
container.id = 'my-ext-app';
container.style.cssText = 'position:fixed;top:20px;right:20px;z-index:9999;background:white;padding:10px;border-radius:4px;';
document.body.appendChild(container);

createRoot(container).render(<App />);

3. 执行npm run build，把打包后的dist/my-react-component.js放到扩展目录里，然后按照方法一的配置在content.js里注入这个文件即可。

常见错误的排查思路 #

你注入React后content.js报错，大概率是这几个原因：

• 未声明web_accessible_resources：Chrome会拦截content script访问未声明的资源，控制台会有类似Not allowed to load local resource的错误。
• React未加载完成就执行组件：如果没等React脚本onload就执行组件代码，会出现React is not defined的错误，所以一定要用Promise或者回调确保加载顺序。
• 上下文冲突：如果页面本身也用了React，你注入的React可能和页面的版本冲突，解决办法是用构建工具把React打包进你的组件脚本，不要依赖页面的全局React。
• Manifest版本问题：v3和v2的web_accessible_resources配置语法不同，v3需要用数组包裹对象，v2是直接数组。

内容的提问来源于stack exchange，提问作者Дмитрий Кузяев