Chrome插件开发完全指南

Chrome插件（正式名称为Chrome扩展程序，Chrome Extension）是基于Web技术（HTML/CSS/JavaScript）开发、用于扩展Chrome浏览器功能的轻量级软件组件。它可以实现页面增强、自动化操作、数据采集、开发辅助等功能，本质是对浏览器能力的“扩展”而非独立应用。本文将从基础概念到实战案例，全面覆盖Chrome插件开发的核心知识。

一、Chrome插件开发概述

1.1 基本概念

Chrome插件并非独立运行的程序，而是依赖Chrome浏览器的“组件集合”，核心由配置文件（Manifest） 和多个功能模块（后台脚本、内容脚本、弹出页等）组成，各模块通过浏览器提供的API协同工作。

1.2 核心功能

Chrome插件的核心能力由浏览器暴露的API支撑，主要包括：

页面注入与DOM操作：向目标网页注入脚本/样式，修改页面结构或样式（如高亮文本、屏蔽广告）。后台任务处理：通过Service Worker监听浏览器事件（如插件安装、标签页切换），执行长时/定时任务（如自动同步数据）。用户交互界面：通过弹出页（Popup）、选项页（Options Page）提供可视化操作入口。浏览器资源访问：操作标签页（打开/关闭/切换）、书签、历史记录、存储数据等。跨源请求：突破普通网页的跨域限制，发起HTTP/HTTPS请求（需声明权限）。

1.3 应用场景

Chrome插件的适用场景广泛，典型案例包括：

生产力工具：如印象笔记网页剪藏、Todoist任务添加、翻译插件（DeepL）。开发辅助：如Vue DevTools、React DevTools、JSON Viewer（格式化JSON数据）。内容增强/过滤：如广告屏蔽（AdBlock）、网页深色模式切换、视频倍速控制。自动化操作：如自动填充表单、批量下载图片、定时刷新页面。

1.4 插件与普通网页开发的区别

插件开发虽基于Web技术，但运行环境和能力与普通网页有本质差异，具体对比如下：

对比维度	普通网页开发	Chrome插件开发
运行环境	浏览器标签页，受同源策略限制	浏览器扩展上下文，隔离于网页
权限范围	仅能操作自身页面DOM/数据	可访问浏览器API（如标签页、存储），需声明权限
生命周期	页面打开时加载，关闭时销毁	组件独立生命周期（如Popup打开时加载，Service Worker空闲时回收）
跨域能力	受同源策略限制，需后端CORS	声明`host_permissions`后可直接跨域请求
资源访问	仅能访问自身服务器资源	可访问网页DOM、浏览器本地存储、系统剪贴板等

1.5 Manifest V3的核心更新

Manifest是插件的“配置清单”，定义了插件的名称、权限、组件等核心信息。目前Chrome主推Manifest V3（2021年发布），替代旧版Manifest V2（2024年起停止审核），核心更新如下：

后台脚本由Service Worker替代
V2中后台逻辑通过background.page（HTML页面）或background.scripts（JS文件）实现，存在内存占用高的问题；V3改用background.service_worker（无界面、事件驱动），空闲时自动回收，性能更优。

权限体系拆分与收紧

原permissions中的网站访问权限（如<all_urls>）拆分到host_permissions，更清晰；移除危险权限（如webRequestBlocking），改用声明式API（如declarativeNetRequest）拦截网络请求；部分权限需用户动态授权（如activeTab仅在用户点击插件时授予当前标签页权限）。

内容安全策略（CSP）强制收紧
V3默认禁止内联脚本（inline script）和eval()，需通过外部JS文件加载逻辑，且content_security_policy配置更严格（如script-src 'self'，仅允许加载插件自身脚本）。

API命名统一
原browserAction/pageAction合并为action，统一插件图标操作逻辑；chrome.extension API逐步废弃，改用chrome.runtime/chrome.tabs等更明确的命名空间。

性能与安全性优化
禁止远程代码注入（仅允许加载插件本地资源），减少恶意插件风险；Service Worker的事件驱动模型降低内存占用。

二、开发环境搭建

Chrome插件开发无需复杂的编译工具，核心依赖“浏览器+代码编辑器”，环境搭建步骤如下：

2.1 必备工具

Chrome浏览器
要求版本≥88（支持Manifest V3），推荐使用最新稳定版。

开启开发者模式：打开Chrome扩展管理页（地址栏输入chrome://extensions/），勾选右上角“开发者模式”。

代码编辑器
推荐使用VS Code，搭配以下插件提升效率：

Chrome Extension Developer Tools：提供Manifest语法提示、API文档跳转；ESLint：检查JS语法错误；Prettier：自动格式化代码。

调试辅助工具

Chrome内置DevTools：调试插件各组件（后台脚本、Popup、内容脚本）；Chrome Extension Reloader：自动刷新插件，避免手动重载。

2.2 环境配置步骤

创建项目目录
新建文件夹（如my-extension），用于存放插件所有文件，建议目录结构如下：


my-extension/
├─ icons/               # 插件图标（不同尺寸）
│  ├─ icon16.png
│  ├─ icon48.png
│  └─ icon128.png
├─ popup/               # 弹出页相关文件
│  ├─ popup.html
│  ├─ popup.css
│  └─ popup.js
├─ background.js        # 后台Service Worker
├─ content-script.js    # 内容脚本
└─ manifest.json        # 核心配置文件

加载未打包插件
在Chrome扩展管理页（chrome://extensions/）点击“加载已解压的扩展程序”，选择上述项目目录，插件即可加载到浏览器（图标显示在地址栏右侧）。

开启自动重载
加载插件后，在扩展管理页勾选“开发者模式”下的“自动刷新”，或使用Chrome Extension Reloader插件，修改代码后无需手动重载。

2.3 调试工具使用

Chrome为插件各组件提供了专属调试入口，核心调试方式如下：

组件类型	调试入口
后台Service Worker	扩展管理页 → 找到插件 → 点击“查看视图” → “Service Worker”，打开DevTools
弹出页（Popup）	点击插件图标打开Popup → 右键Popup空白处 → 选择“检查”，打开Popup的DevTools
内容脚本	打开目标网页 → 按F12打开网页DevTools → 切换到“Sources” → “Content scripts” → 找到插件脚本
选项页（Options）	扩展管理页 → 插件“详情” → “扩展选项” → 右键选项页 → “检查”

调试技巧：

后台脚本：用console.log()打印日志，在Service Worker的DevTools中查看；内容脚本：断点调试DOM操作，需在网页DevTools的“Content scripts”面板设置断点；Popup：调试CSS样式时，可在DevTools的“Elements”面板实时修改样式。

三、Manifest V3文件解析

manifest.json是插件的“身份证”，所有配置均为JSON格式（不支持注释，需删除注释后使用）。以下是Manifest V3的核心字段解析及配置示例。

3.1 必填字段（必须配置）

字段名	类型	说明
`manifest_version`	数字	固定为`3`（Manifest V3标识，V2为`2`）
`name`	字符串	插件名称（显示在扩展管理页、应用商店）
`version`	字符串	插件版本号（格式如`1.0.0`，更新时需递增）

示例：


{
  "manifest_version": 3,
  "name": "我的第一个Chrome插件",
  "version": "1.0.0"
}

3.2 常用可选字段（核心配置）

以下字段是大多数插件的核心配置，需根据功能需求选择：

1. 基础信息字段

description：插件描述（≤132字符，显示在扩展管理页）；icons：插件图标（不同尺寸适配不同场景，建议提供16×16、48×48、128×128像素）；default_locale：默认语言（如"zh_CN"，用于多语言适配）。

示例：


"description": "一个用于高亮网页文本的Chrome插件",
"icons": {
  "16": "icons/icon16.png",
  "48": "icons/icon48.png",
  "128": "icons/icon128.png"
},
"default_locale": "zh_CN"

2. 权限相关字段

权限分为“浏览器API权限”和“网站访问权限”，需明确声明才能使用对应能力。

字段名	类型	说明
`permissions`	数组	浏览器API权限，如`storage`（本地存储）、`activeTab`（当前标签页权限）、`scripting`（动态注入脚本）
`host_permissions`	数组	网站访问权限，如`"<all_urls>"`（所有网站）、`"https://.baidu.com/"`（百度域名）
`optional_permissions`	数组	可选权限（用户可手动授权/拒绝），如`"history"`（访问历史记录）

示例：


"permissions": ["storage", "activeTab", "scripting", "contextMenus"],
"host_permissions": ["<all_urls>"],
"optional_permissions": ["history"]

3. 后台脚本配置（`background`）

用于配置后台Service Worker，处理事件监听、长时任务等。

service_worker：指定Service Worker文件路径（仅支持单个JS文件，不支持HTML）；type：可选，指定脚本类型（如"module"，支持ES模块）。

示例：


"background": {
  "service_worker": "background.js",
  "type": "module"
}

4. 内容脚本配置（`content_scripts`）

用于向目标网页注入脚本/样式，配置项如下：

matches：指定注入的网页（如"<all_urls>"、"https://*.google.com/*"）；js：注入的JS文件数组；css：注入的CSS文件数组；run_at：注入时机（"document_start"/"document_end"/"document_idle"，默认document_idle）；all_frames：是否注入到iframe中（true/false，默认false）。

示例：


"content_scripts": [
  {
    "matches": ["<all_urls>"],
    "js": ["content-script.js"],
    "css": ["content-script.css"],
    "run_at": "document_end",
    "all_frames": false
  }
]

5. 弹出页配置（`action`）

配置插件图标和弹出页，action是V3对V2中browserAction/pageAction的统一。

default_popup：弹出页HTML路径；default_icon：插件图标（默认状态）；default_title：鼠标悬浮图标时的提示文本。

示例：


"action": {
  "default_popup": "popup/popup.html",
  "default_icon": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png"
  },
  "default_title": "网页高亮插件"
}

6. 其他常用字段

options_page/options_ui：配置插件选项页（用户修改插件设置的页面）；web_accessible_resources：声明网页可访问的插件资源（如图片、CSS，避免跨域问题）；content_security_policy：内容安全策略（CSP），V3默认"script-src 'self'; object-src 'self'"，禁止内联脚本。

示例（选项页+CSP）：


"options_ui": {
  "page": "options/options.html",
  "open_in_tab": true  // 在新标签页打开选项页
},
"content_security_policy": {
  "extension_pages": "script-src 'self'; object-src 'self'; style-src 'self' 'unsafe-inline'"
}

3.3 完整Manifest V3示例


{
  "manifest_version": 3,
  "name": "网页高亮插件",
  "version": "1.0.0",
  "description": "高亮网页中的选中文本，支持自定义颜色和记录管理",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": ["storage", "activeTab", "scripting", "contextMenus"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content-script.js"],
      "css": ["content-script.css"],
      "run_at": "document_end"
    }
  ],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": "icons/icon16.png",
    "default_title": "网页高亮"
  },
  "options_ui": {
    "page": "options/options.html",
    "open_in_tab": true
  },
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'; style-src 'self' 'unsafe-inline'"
  }
}

四、核心功能模块开发

Chrome插件的功能由“后台脚本、内容脚本、弹出页”三大核心模块支撑，各模块分工明确，需通过浏览器API协同工作。

4.1 后台脚本（Background Script）

后台脚本是插件的“大脑”，运行在Service Worker中，负责监听浏览器事件、处理全局逻辑（如数据同步、定时任务）。

核心特性

无界面：没有DOM，无法直接操作网页；事件驱动：仅在事件触发时激活（如插件安装、收到消息），空闲时被Chrome回收；全局访问：可访问几乎所有Chrome API（需声明权限）。

开发示例：监听事件与处理消息

监听插件安装事件：安装时创建右键菜单、初始化存储数据。


// background.js
chrome.runtime.onInstalled.addListener((details) => {
  // 1. 创建右键菜单（选中文字时显示“高亮文本”）
  chrome.contextMenus.create({
    id: "highlight-text",
    title: "高亮选中文字",
    contexts: ["selection"]  // 仅在选中文本时显示
  });

  // 2. 初始化存储（默认高亮颜色为黄色）
  chrome.storage.local.set({ highlightColor: "#ffff00" }, () => {
    console.log("默认高亮颜色已初始化");
  });
});

监听右键菜单点击事件：用户点击菜单时，调用scripting API注入逻辑高亮文本。


chrome.contextMenus.onClicked.addListener(async (info, tab) => {
  if (info.menuItemId === "highlight-text") {
    // 获取选中的文本
    const selectedText = info.selectionText;
    if (!selectedText) return;

    // 获取存储的高亮颜色
    const { highlightColor } = await chrome.storage.local.get("highlightColor");

    // 向当前标签页注入脚本，执行高亮逻辑
    await chrome.scripting.executeScript({
      target: { tabId: tab.id },  // 目标标签页ID
      func: (text, color) => {
        // 此函数在网页上下文执行，可操作DOM
        const selection = window.getSelection();
        if (selection.rangeCount === 0) return;
        const range = selection.getRangeAt(0);
        const span = document.createElement("span");
        span.style.backgroundColor = color;
        span.textContent = text;
        range.deleteContents();
        range.insertNode(span);
      },
      args: [selectedText, highlightColor]  // 传递给func的参数
    });
  }
});

监听来自Popup的消息：处理Popup发送的“获取高亮记录”请求。


chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GET_HIGHLIGHT_RECORDS") {
    // 从存储中获取所有高亮记录
    chrome.storage.local.get("highlightRecords", (result) => {
      const records = result.highlightRecords || [];
      sendResponse({ status: "success", records });
    });
    // 异步响应需返回true
    return true;
  }
});

注意事项

长时任务：避免在Service Worker中执行耗时操作（如大型循环），可使用chrome.alarms定时拆分任务；数据持久化：Service Worker回收后内存数据丢失，需用chrome.storage存储关键数据；API限制：无法使用window/document等DOM API，需操作网页时通过scripting API注入脚本。

4.2 内容脚本（Content Script）

内容脚本是插件与网页交互的“桥梁”，运行在目标网页的“隔离环境”中，可直接操作网页DOM，但权限受限。

核心特性

隔离环境：运行在“Isolated World”，无法访问网页自身的JS变量（如window上的全局变量），但可共享DOM；DOM访问：可直接读取/修改网页DOM、CSS；权限限制：仅能访问部分Chrome API（如runtime.sendMessage、storage），无法访问tabs/contextMenus等API。

开发示例：注入脚本与通信

注入CSS样式：提前定义高亮元素的样式（也可通过manifest.json的content_scripts.css注入）。


/* content-script.css */
.highlight-span {
  background-color: #ffff00;
  padding: 2px 0;
  cursor: pointer;
}
.highlight-span:hover {
  opacity: 0.8;
}

监听来自后台/Popup的消息：接收“高亮文本”“清除高亮”指令。


// content-script.js
// 监听来自后台/Popup的消息
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  switch (message.type) {
    case "HIGHLIGHT_TEXT":
      highlightSelectedText(message.color);
      sendResponse({ status: "success" });
      break;
    case "CLEAR_HIGHLIGHT":
      clearAllHighlights();
      sendResponse({ status: "success" });
      break;
    default:
      sendResponse({ status: "error", message: "未知指令" });
  }
});

// 高亮选中的文本
function highlightSelectedText(color) {
  const selection = window.getSelection();
  if (selection.rangeCount === 0) return;

  const range = selection.getRangeAt(0);
  const selectedText = range.toString().trim();
  if (!selectedText) return;

  // 创建高亮元素
  const span = document.createElement("span");
  span.className = "highlight-span";
  span.style.backgroundColor = color;
  span.textContent = selectedText;

  // 替换选中的文本为高亮元素
  range.deleteContents();
  range.insertNode(span);

  // 保存高亮记录到存储（通过后台脚本中转，因内容脚本无权限直接操作所有存储）
  chrome.runtime.sendMessage({
    type: "SAVE_HIGHLIGHT_RECORD",
    data: {
      text: selectedText,
      color: color,
      url: window.location.href,
      title: document.title,
      time: new Date().toISOString()
    }
  });
}

// 清除当前页面所有高亮
function clearAllHighlights() {
  const highlights = document.querySelectorAll(".highlight-span");
  highlights.forEach(span => {
    // 用文本节点替换高亮元素，保留原文本
    const textNode = document.createTextNode(span.textContent);
    span.parentNode.replaceChild(textNode, span);
  });
}

与网页上下文通信：因内容脚本无法访问网页JS变量，需通过DOM自定义事件传递数据。


// 内容脚本：发送事件给网页
const event = new CustomEvent("contentScriptMessage", {
  detail: { type: "GET_PAGE_DATA" }
});
window.dispatchEvent(event);

// 网页脚本：监听事件并响应
window.addEventListener("contentScriptMessage", (event) => {
  if (event.detail.type === "GET_PAGE_DATA") {
    const pageData = { title: document.title, url: window.location.href };
    // 发送响应事件
    window.dispatchEvent(new CustomEvent("pageResponse", { detail: pageData }));
  }
});

// 内容脚本：监听网页的响应
window.addEventListener("pageResponse", (event) => {
  console.log("网页数据：", event.detail);
});

注意事项

注入方式：除了manifest.json配置的静态注入，还可通过chrome.scripting.executeScript动态注入（需scripting权限）；样式隔离：内容脚本的CSS会影响网页全局，建议使用唯一类名（如highlight-span）避免冲突；跨域请求：内容脚本发起跨域请求需在manifest.json中声明host_permissions，或通过后台脚本中转。

4.3 弹出页面（Popup）

Popup是插件的“用户界面”，点击插件图标时打开，关闭后立即销毁（生命周期短），适合提供简单交互（如设置、操作按钮）。

核心特性

轻量级界面：基于HTML/CSS，尺寸建议≤800x600px；短暂生命周期：打开时加载HTML/JS，关闭后所有内存数据丢失；通信依赖：需通过chrome.runtime.sendMessage与后台/内容脚本通信，数据需存储在chrome.storage中。

开发示例：高亮设置与记录管理

Popup HTML结构：包含颜色选择器、高亮按钮、清除按钮、记录列表。


<!-- popup/popup.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>网页高亮</title>
  <link rel="stylesheet" href="popup.css">
</head>
<body>
  <div class="container">
    <h3>高亮设置</h3>
    <!-- 颜色选择器 -->
    <div class="setting-item">
      <label>高亮颜色：</label>
      <input type="color" id="colorPicker">
    </div>
    <!-- 操作按钮 -->
    <div class="button-group">
      <button id="highlightBtn">高亮选中文字</button>
      <button id="clearBtn">清除当前页面高亮</button>
    </div>

    <h3>高亮记录</h3>
    <ul id="recordList"></ul>
  </div>
  <script src="popup.js"></script>
</body>
</html>

Popup CSS样式：设置固定宽度，优化布局。


/* popup/popup.css */
body {
  width: 300px;
  padding: 15px;
  margin: 0;
  font-family: Arial, sans-serif;
}
.container {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.setting-item {
  display: flex;
  align-items: center;
  gap: 8px;
}
#colorPicker {
  width: 30px;
  height: 30px;
  border: none;
  padding: 0;
  cursor: pointer;
}
.button-group {
  display: flex;
  gap: 8px;
}
button {
  flex: 1;
  padding: 6px;
  border: 1px solid #ccc;
  border-radius: 4px;
  background: #fff;
  cursor: pointer;
}
button:hover {
  background: #f5f5f5;
}
#recordList {
  list-style: none;
  padding: 0;
  max-height: 200px;
  overflow-y: auto;
  gap: 8px;
  display: flex;
  flex-direction: column;
}
.record-item {
  padding: 8px;
  border: 1px solid #eee;
  border-radius: 4px;
  font-size: 12px;
}
.record-text {
  margin-bottom: 4px;
  word-break: break-all;
}
.record-meta {
  color: #666;
  font-size: 10px;
  display: flex;
  justify-content: space-between;
}

Popup JS逻辑：加载配置、发送消息、渲染记录。


// popup/popup.js
document.addEventListener("DOMContentLoaded", async () => {
  const colorPicker = document.getElementById("colorPicker");
  const highlightBtn = document.getElementById("highlightBtn");
  const clearBtn = document.getElementById("clearBtn");
  const recordList = document.getElementById("recordList");

  // 1. 加载存储的高亮颜色，设置颜色选择器默认值
  const { highlightColor } = await chrome.storage.local.get("highlightColor");
  colorPicker.value = highlightColor || "#ffff00";

  // 2. 颜色选择器变化时，保存到存储
  colorPicker.addEventListener("change", (e) => {
    chrome.storage.local.set({ highlightColor: e.target.value });
  });

  // 3. 点击“高亮选中文字”按钮，向内容脚本发送指令
  highlightBtn.addEventListener("click", async () => {
    // 获取当前活跃标签页
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (!tab.id) return;

    // 向当前标签页的内容脚本发送消息
    try {
      const response = await chrome.tabs.sendMessage(tab.id, {
        type: "HIGHLIGHT_TEXT",
        color: colorPicker.value
      });
      console.log("高亮结果：", response);
    } catch (error) {
      alert("请先选中文本，或刷新页面后重试！");
    }
  });

  // 4. 点击“清除高亮”按钮，向内容脚本发送指令
  clearBtn.addEventListener("click", async () => {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (!tab.id) return;

    await chrome.tabs.sendMessage(tab.id, { type: "CLEAR_HIGHLIGHT" });
  });

  // 5. 加载并渲染高亮记录
  const loadRecords = async () => {
    // 向后台脚本发送消息，获取记录（内容脚本无权限访问所有记录，通过后台中转）
    const response = await chrome.runtime.sendMessage({
      type: "GET_HIGHLIGHT_RECORDS"
    });

    if (response.status === "success" && response.records.length > 0) {
      recordList.innerHTML = response.records
        .map((record, index) => `
          <li class="record-item">
            <div class="record-text">
              ${record.text}
            </div>
            <div class="record-meta">
              <span>${new Date(record.time).toLocaleString()}</span>
              <span>${record.title}</span>
            </div>
          </li>
        `)
        .join("");
    } else {
      recordList.innerHTML = "<li>暂无高亮记录</li>";
    }
  };

  // 初始加载记录
  loadRecords();
});

注意事项

数据持久化：Popup关闭后数据丢失，需将配置/记录存储在chrome.storage中；尺寸控制：Popup高度超过屏幕时会出现滚动条，建议控制内容长度（如记录列表设置max-height）；依赖DOM加载：JS逻辑需放在DOMContentLoaded事件中，确保HTML元素已渲染。

五、插件通信机制

Chrome插件的各组件（Popup、后台脚本、内容脚本、选项页）运行在独立上下文，需通过浏览器提供的API实现通信。核心通信方式分为“短连接（一次性消息）”和“长连接（持续交互）”。

5.1 核心通信API对比

通信方式	API	使用场景	特点
短连接（全局）	`chrome.runtime.sendMessage`	Popup ↔ 后台、选项页 ↔ 后台	一次性消息，异步响应，无连接状态
短连接（定向标签页）	`chrome.tabs.sendMessage`	Popup ↔ 内容脚本、后台 ↔ 内容脚本	定向到特定标签页的内容脚本，需知道`tabId`
长连接	`chrome.runtime.connect`	频繁交互场景（如Popup ↔ 内容脚本持续通信）	建立持久连接，可双向发送多条消息

5.2 短连接通信（一次性消息）

短连接适用于“发送一条消息并获取响应”的场景，如Popup请求后台获取数据、后台指令内容脚本执行操作。

1. 全局通信：`chrome.runtime.sendMessage`

场景：Popup向后台脚本发送请求，获取高亮记录。

发送方（Popup）：


// popup.js
async function getRecords() {
  try {
    // 发送消息：{type: "GET_RECORDS"}
    const response = await chrome.runtime.sendMessage({
      type: "GET_RECORDS"
    });
    console.log("后台返回的记录：", response.records);
    return response.records;
  } catch (error) {
    console.error("通信失败：", error);
    return [];
  }
}

接收方（后台脚本）：


// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 验证消息类型
  if (message.type === "GET_RECORDS") {
    // 从存储中获取记录
    chrome.storage.local.get("highlightRecords", (result) => {
      const records = result.highlightRecords || [];
      // 发送响应
      sendResponse({ status: "success", records });
    });
    // 异步响应需返回true（告知Chrome等待sendResponse调用）
    return true;
  }
});

2. 定向通信：`chrome.tabs.sendMessage`

场景：Popup向当前标签页的内容脚本发送“高亮文本”指令，需指定tabId。

发送方（Popup）：


// popup.js
async function sendHighlightCommand(color) {
  // 获取当前活跃标签页
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
  if (!tab.id) return;

  try {
    // 向tabId对应的内容脚本发送消息
    const response = await chrome.tabs.sendMessage(tab.id, {
      type: "HIGHLIGHT",
      color: color
    });
    alert(response.status);
  } catch (error) {
    alert("内容脚本未加载，刷新页面后重试！");
  }
}

接收方（内容脚本）：


// content-script.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "HIGHLIGHT") {
    highlightSelectedText(message.color); // 调用高亮函数
    sendResponse({ status: "高亮成功！" });
  }
});

5.3 长连接通信（`chrome.runtime.connect`）

长连接适用于“多次交互”场景，如Popup实时获取内容脚本的高亮进度、内容脚本持续向后台发送数据。建立连接后，双方可通过port对象发送/接收消息。

开发示例：Popup与内容脚本建立长连接

发起连接（Popup）：


// popup.js
document.addEventListener("DOMContentLoaded", async () => {
  // 获取当前标签页
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
  if (!tab.id) return;

  // 建立长连接，指定标签页ID
  const port = chrome.tabs.connect(tab.id, { name: "highlight-connection" });

  // 1. 监听连接状态（如内容脚本断开连接）
  port.onDisconnect.addListener(() => {
    console.log("与内容脚本的连接已断开");
  });

  // 2. 监听内容脚本发送的消息（如高亮进度）
  port.onMessage.addListener((message) => {
    if (message.type === "HIGHLIGHT_PROGRESS") {
      console.log(`高亮进度：${message.progress}%`);
    }
  });

  // 3. 向内容脚本发送消息（如“开始批量高亮”）
  document.getElementById("batchHighlightBtn").addEventListener("click", () => {
    port.postMessage({ type: "START_BATCH_HIGHLIGHT", keyword: "Chrome" });
  });
});

接收连接（内容脚本）：


// content-script.js
// 监听Popup发起的连接
chrome.runtime.onConnect.addListener((port) => {
  // 验证连接名称（防止其他插件伪造连接）
  if (port.name !== "highlight-connection") return;

  // 1. 监听Popup发送的消息
  port.onMessage.addListener((message) => {
    if (message.type === "START_BATCH_HIGHLIGHT") {
      // 执行批量高亮逻辑，并实时发送进度
      batchHighlight(message.keyword, (progress) => {
        port.postMessage({ type: "HIGHLIGHT_PROGRESS", progress });
      });
    }
  });

  // 2. 连接断开时的清理逻辑
  port.onDisconnect.addListener(() => {
    console.log("与Popup的连接已断开");
  });
});

// 批量高亮包含指定关键词的文本
function batchHighlight(keyword, progressCallback) {
  const texts = document.querySelectorAll("p, div, span");
  const total = texts.length;
  let completed = 0;

  texts.forEach((textNode) => {
    if (textNode.textContent.includes(keyword)) {
      // 高亮关键词（简化逻辑）
      textNode.innerHTML = textNode.innerHTML.replace(
        new RegExp(keyword, "g"),
        `<span>${keyword}</span>`
      );
    }
    completed++;
    // 发送进度（百分比）
    progressCallback(Math.floor((completed / total) * 100));
  });
}

5.4 通信安全注意事项

验证消息来源：接收消息时检查sender.id（插件ID），确保消息来自自身插件，防止恶意网页伪造消息：


chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 验证发送方是当前插件（sender.id为插件ID，可在manifest中查看）
  if (sender.id !== "你的插件ID") {
    sendResponse({ status: "error", message: "非法消息来源" });
    return;
  }
  // 处理合法消息...
});

验证消息格式：接收消息时检查message.type和必要参数，避免非法指令：


if (message.type === "HIGHLIGHT" && message.color) {
  // 处理高亮逻辑
} else {
  sendResponse({ status: "error", message: "无效指令或参数缺失" });
}

避免敏感数据传输：通信中不传递密码、令牌等敏感信息，如需传递需加密。

六、数据存储与权限管理

Chrome插件提供多种数据存储方式，其中chrome.storage API是官方推荐的核心方案，支持本地存储和跨设备同步；权限管理则需遵循“最小权限原则”，确保插件安全合规。

6.1 数据存储方案：`chrome.storage` API

chrome.storage是插件专用的存储API，相比普通网页的localStorage有明显优势：

跨组件访问：Popup、后台脚本、内容脚本均可访问；异步操作：避免阻塞主线程；更大容量：local存储约5MB，sync存储约100KB（跨设备同步）；支持结构化数据：可直接存储对象、数组，无需手动序列化（localStorage需JSON.stringify）。

1. 存储模式对比

存储模式	特点	适用场景
`chrome.storage.local`	本地存储，不同步，容量大（约5MB）	插件配置、大量本地数据（如高亮记录）
`chrome.storage.sync`	同步到用户的Chrome账号，多设备共享，容量小（约100KB）	用户偏好（如默认高亮颜色）
`chrome.storage.session`	会话存储，关闭浏览器后清除，容量小（约1MB）	临时数据（如当前会话的高亮状态）

2. 核心API使用示例

chrome.storage的所有方法均为异步，支持回调函数或async/await（推荐）。

（1）存储数据（`set`）


// 存储单个键值对
await chrome.storage.local.set({ highlightColor: "#ffff00" });

// 存储多个键值对
await chrome.storage.sync.set({
  username: "user123",
  enableAutoHighlight: true
});

（2）读取数据（`get`）


// 读取指定键的数据
const { highlightColor } = await chrome.storage.local.get("highlightColor");
console.log("高亮颜色：", highlightColor);

// 读取多个键的数据（不存在的键返回undefined）
const { username, enableAutoHighlight } = await chrome.storage.sync.get([
  "username",
  "enableAutoHighlight"
]);

// 读取所有数据
const allData = await chrome.storage.local.get(null);
console.log("所有本地存储数据：", allData);

（3）删除数据（`remove`）


// 删除单个键
await chrome.storage.local.remove("highlightColor");

// 删除多个键
await chrome.storage.sync.remove(["username", "enableAutoHighlight"]);

（4）清空数据（`clear`）


// 清空所有本地存储数据
await chrome.storage.local.clear();

// 清空所有同步存储数据
await chrome.storage.sync.clear();

（5）监听数据变化（`onChanged`）

当存储数据变化时触发，适用于多组件同步更新（如Popup修改配置后，内容脚本实时更新样式）：


// 内容脚本中监听存储变化
chrome.storage.onChanged.addListener((changes, areaName) => {
  // changes：变化的数据（{key: {oldValue, newValue}}）
  // areaName：存储区域（"local"/"sync"/"session"）
  if (areaName === "local" && changes.highlightColor) {
    const newColor = changes.highlightColor.newValue;
    console.log("高亮颜色已更新为：", newColor);
    // 更新现有高亮元素的颜色
    const highlights = document.querySelectorAll(".highlight-span");
    highlights.forEach(span => {
      span.style.backgroundColor = newColor;
    });
  }
});

3. 使用注意事项

权限声明：使用chrome.storage需在manifest.json中声明"storage"权限；数据类型限制：不支持存储Function、Date、RegExp等特殊对象，需转为基础类型（如Date转为字符串）；容量限制：避免存储过大数据（如Base64图片），建议通过chrome.downloads API下载到本地。

6.2 权限管理最佳实践

Chrome插件的权限分为“必填权限”和“可选权限”，权限申请需遵循“最小必要原则”，避免因权限滥用导致审核被拒或用户不信任。

1. 核心权限说明

权限名称	用途	风险等级
`activeTab`	仅在用户点击插件图标时，授予当前标签页的临时权限（如注入脚本、访问DOM）	低
`storage`	访问`chrome.storage`本地/同步存储	低
`scripting`	动态注入脚本/样式到网页	中
`host_permissions`	访问指定网站的DOM或发起跨域请求	中（`<all_urls>`为高）
`tabs`	访问标签页信息（如URL、标题）	中
`contextMenus`	创建浏览器右键菜单	低

2. 权限申请策略

优先使用activeTab替代<all_urls>
activeTab仅在用户主动点击插件时授予当前标签页权限，比<all_urls>（访问所有网站）更安全，也更容易通过Chrome应用商店审核。
示例：用户点击插件图标后，注入脚本操作当前页面：


// background.js
chrome.action.onClicked.addListener(async (tab) => {
  // 授予当前标签页activeTab权限，并注入脚本
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ["content-script.js"]
  });
});

可选权限动态申请
非核心功能的权限（如访问历史记录、书签）应设为optional_permissions，在用户使用对应功能时再动态申请，而非安装时强制要求。
示例：申请history权限查看浏览历史：


// manifest.json
"optional_permissions": ["history"]


// popup.js：用户点击“查看历史高亮页面”时申请权限
document.getElementById("viewHistoryBtn").addEventListener("click", async () => {
  // 检查是否已授予权限
  const hasPermission = await chrome.permissions.contains({
    permissions: ["history"]
  });

  if (hasPermission) {
    // 已授权，访问历史记录
    chrome.history.search({ text: "highlight" }, (results) => {
      console.log("历史高亮页面：", results);
    });
  } else {
    // 未授权，动态申请
    const granted = await chrome.permissions.request({
      permissions: ["history"]
    });

    if (granted) {
      alert("权限已授予，可查看历史记录！");
    } else {
      alert("权限被拒绝，无法查看历史记录！");
    }
  }
});

明确权限用途
提交Chrome应用商店时，需在“商品描述”中详细说明每个权限的用途，让用户理解“为什么需要该权限”，例如：

“storage权限：用于保存您的高亮颜色配置和历史记录，不会上传到服务器。”“activeTab权限：仅在您点击插件时，临时访问当前网页以实现文本高亮，不访问其他页面。”

3. 权限安全注意事项

避免过度申请权限：不申请与功能无关的权限（如仅做文本高亮，无需history或bookmarks权限）；定期审查权限：插件更新时，移除不再使用的权限；敏感权限处理：涉及用户隐私的权限（如history、tabs），需在插件内提供“权限管理”入口，允许用户随时关闭。

七、调试与发布流程

插件开发完成后，需通过调试修复问题，再打包发布到Chrome应用商店，供用户安装使用。

7.1 调试技巧（各组件全覆盖）

Chrome提供了完善的调试工具，可针对不同组件进行精准调试：

1. 后台Service Worker调试

入口：扩展管理页（chrome://extensions/）→ 找到插件 → 点击“查看视图” → “Service Worker”；调试功能：
Console：查看console.log输出，执行临时JS代码；Sources：设置断点，单步调试后台脚本；Application：查看chrome.storage存储数据，模拟Service Worker回收（“Service Workers” → 选中脚本 → “Stop”）。

技巧：Service Worker空闲时会被回收，可在“Sources”面板勾选“Pause on caught exceptions”，捕获回收前的异常。

2. 内容脚本调试

入口：打开目标网页 → 按F12打开网页DevTools → 切换到“Sources” → 左侧导航栏找到“Content scripts” → 展开插件名称 → 选择要调试的脚本；调试功能：
断点调试：点击行号设置断点，单步执行（F10）、进入函数（F11）；DOM检查：在“Elements”面板查看内容脚本注入的DOM元素（如高亮的span标签）；Network：查看内容脚本发起的网络请求（需在“Network”面板勾选“All”）。

技巧：内容脚本无法访问网页的window变量，可在“Console”面板切换到“Content scripts”上下文（顶部下拉菜单），直接打印插件脚本的变量。

3. 弹出页（Popup）调试

入口：点击插件图标打开Popup → 右键Popup空白处 → 选择“检查”；调试功能：
Elements：实时修改HTML/CSS，预览样式效果；Sources：调试Popup的JS脚本，设置断点；Console：查看Popup的console.log输出，测试API调用。

技巧：Popup关闭后调试窗口会消失，可在调试窗口右上角点击“分离”（图标为□），保持调试窗口独立。

4. 常见调试问题与解决

问题现象	可能原因	解决方案
内容脚本无响应	脚本未注入（`matches`配置错误）或无权限	检查`manifest.json`的`content_scripts.matches`，确保包含目标网页；刷新插件和网页
后台脚本断点不生效	Service Worker已被回收	在“Service Worker”调试窗口点击“Refresh”，重新激活脚本；在事件监听处设置断点
Popup打开后立即关闭	Popup的HTML/CSS错误（如语法错误）	检查Popup的HTML结构，用“检查”查看Console报错；简化CSS，排除样式冲突
`chrome.storage`数据不更新	异步操作未等待完成，或键名错误	使用`async/await`确保`set`完成后再`get`；检查键名是否一致

7.2 发布流程（Chrome应用商店）

Chrome插件需发布到Chrome Web Store（Chrome应用商店），用户才能通过浏览器搜索安装。发布需完成账号注册、插件打包、信息填写、审核等步骤。

1. 发布前准备

注册Chrome开发者账号：

访问Chrome Web Store Developer Dashboard；用Google账号登录，支付一次性注册费（5美元，用于验证开发者身份）；完成账号信息填写（如开发者名称、联系方式）。

插件打包：

确保插件符合Chrome Web Store政策（如无恶意代码、权限合理）；打包为ZIP文件：将插件项目目录（包含manifest.json、脚本、图标等）压缩为ZIP（注意：ZIP根目录需直接包含manifest.json，不能嵌套子文件夹）；（可选）打包为CRX文件：扩展管理页 → “打包扩展程序” → 选择项目目录 → 生成CRX（私钥文件.pem需保存，下次更新插件需使用）。

准备发布素材：

图标：至少提供128×128像素的图标（用于应用商店展示），建议同时提供48×48、16×16像素图标；截图/视频：展示插件功能的截图（至少1张，尺寸建议1280×800像素），或演示视频（YouTube链接）；商品描述：包含插件功能、使用方法、权限用途，语言需与manifest.json的default_locale一致（如中文描述需default_locale: "zh_CN"）。

2. 提交到Chrome应用商店

上传插件：

登录Chrome开发者后台（Dashboard）；点击“新建商品” → 上传ZIP包（或CRX） → 系统自动验证manifest.json格式和权限；若验证失败，根据提示修复（如Manifest字段错误、权限未声明）。

填写商品信息：

基本信息：插件名称、描述（短描述≤132字符，长描述详细说明功能）、类别（如“生产力”“开发工具”）；媒体资源：上传图标、截图、视频，预览展示效果；权限声明：在“权限”标签页，详细说明每个权限的用途（如“storage用于保存用户配置”）；联系信息：填写开发者邮箱（用于接收审核通知）。

提交审核：

确认所有信息无误后，点击“提交发布”；审核周期：通常1-3个工作日，复杂插件可能更长；审核结果：审核通过后，插件将在Chrome应用商店上线（地址为https://chrome.google.com/webstore/detail/插件ID）；若审核失败，根据邮件提示修改（如权限用途不明确、功能不符合政策）。

3. 插件更新流程

插件需要修复bug或添加新功能时，需提交更新：

更新版本号：修改manifest.json的version字段（如从1.0.0改为1.0.1）；打包新版本：重新压缩项目目录为ZIP包；提交更新：开发者后台 → 选择插件 → 点击“上传新包” → 上传ZIP → 填写更新说明（如“修复了高亮文本消失的bug”） → 提交审核；用户更新：审核通过后，用户的Chrome浏览器会自动更新插件（通常24小时内），或用户手动在扩展管理页点击“更新”。

4. 发布注意事项

政策合规：严格遵守Chrome Web Store政策，禁止以下行为：
恶意代码（如挖矿、窃取用户数据）；误导性描述（如功能与描述不符）；过度申请权限（如无需访问所有网站却声明<all_urls>）； 隐私政策：若插件收集用户数据（如chrome.storage.sync同步配置），需提供隐私政策链接（可托管在GitHub Pages或个人网站）；多语言适配：若目标用户为全球用户，需提供多语言描述和界面（通过_locales目录实现）；测试兼容性：确保插件在最新版Chrome中正常运行，避免依赖已废弃的API。

八、实战案例：开发一个网页高亮插件

本节通过一个完整的“网页高亮插件”案例，串联前面的核心知识点，涵盖需求设计、代码实现、调试和打包全流程。

8.1 功能设计（明确需求）

插件核心功能：

文本高亮：用户选中文本后，点击右键菜单或Popup按钮，将文本高亮（支持自定义颜色）；高亮管理：保存高亮记录（文本、颜色、页面URL、时间），在Popup中查看；批量操作：清除当前页面所有高亮，删除指定高亮记录；配置同步：用户的高亮颜色配置同步到Chrome账号（多设备共享）。

8.2 项目结构


highlight-extension/
├─ icons/               # 插件图标
│  ├─ icon16.png
│  ├─ icon48.png
│  └─ icon128.png
├─ popup/               # 弹出页
│  ├─ popup.html
│  ├─ popup.css
│  └─ popup.js
├─ background.js        # 后台Service Worker
├─ content-script.js    # 内容脚本
├─ content-script.css   # 内容脚本样式
└─ manifest.json        # 核心配置文件

8.3 代码实现（分模块开发）

1. Manifest V3配置（`manifest.json`）


{
  "manifest_version": 3,
  "name": "网页文本高亮",
  "version": "1.0.0",
  "description": "高亮网页中的选中文本，支持自定义颜色和记录管理，配置跨设备同步",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": ["storage", "activeTab", "scripting", "contextMenus"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content-script.js"],
      "css": ["content

内容分享

文章版权归作者所有，未经允许请勿转载。

新总觉得手机在“偷听”？这样操作就能关掉“监听”

内容分享

3天前

000

新蓝屏分析工具

内容分享

5天前

000

新深度剖析AI应用架构师的AI评估系统研究成果

内容分享

6天前

020

新AI应用架构师必知：社交媒体用户画像架构的设计与优化

内容分享

5天前

000

暂无评论

暂无评论...

Chrome插件开发完全指南