Chrome 插件开发实战指南：从入门到发布

目录

• 1. 引言
• 2. 环境准备与基础概念
• 3. manifest.json 清单文件详解
• 4. 第一个插件：Hello World 实战
• 5. 内容脚本与页面交互
• 6. 后台脚本与消息通信机制
• 7. 数据存储与设置页面
• 8. 实战项目：网页划词翻译插件
• 9. 调试、测试与性能优化
• 10. 打包与发布到 Chrome 应用商店
• 11. 总结与进阶方向

1. 引言

Chrome 插件（Extension）是运行在浏览器中的小型应用，可以扩展浏览器功能、提升工作效率。本文将从零开始，带你掌握 Chrome 插件开发的核心知识，并完成一个可发布的实战项目。

TL;DR

• MV3 清单文件：manifest_version 固定为 3，通过 manifest.json 声明权限、入口和资源，是插件的核心配置。
• content script 注入：在 manifest 中通过 content_scripts 静态声明，或使用 scripting API 动态注入，用于读取和修改网页 DOM。
• 消息通信：popup、content、background 三者之间通过 chrome.runtime.sendMessage 和 chrome.runtime.connect 完成消息传递。
• 数据存储：使用 chrome.storage.local 和 chrome.storage.sync 持久化用户配置，并通过 onChanged 监听数据变化。
• 打包发布：生成 .crx 文件或上传源码目录，注册 Chrome Web Store 开发者账号后提交审核即可上线。

2. 环境准备与基础概念

在动手开发前，先了解 Chrome 插件的基本构成和开发环境。

• 开发工具：Chrome 浏览器、文本编辑器（VS Code 等）、Node.js（可选）。
• 核心文件：manifest.json 清单文件、background.js 后台脚本、content.js 内容脚本、popup.html 弹窗页面。
• 插件类型：工具栏按钮插件、右键菜单插件、页面内容注入插件、开发者工具插件等。

3. manifest.json 清单文件详解

manifest.json 是插件的配置文件，声明了插件的权限、入口和资源。

• 基础字段：manifest_version、name、version、description。
• 权限声明：permissions 数组，如 storage、tabs、activeTab、scripting。
• 入口配置：background、content_scripts、action（或 browser_action）。
• 图标与语言：icons、default_locale。

4. 第一个插件：Hello World 实战

通过一个最简单的插件，跑通「加载-运行-调试」全流程。下面给出完整的 manifest.json 和 popup.html 代码示例，并标注关键字段的注释说明。

4.1 创建项目目录

新建一个名为 hello-world 的目录，在其中创建 manifest.json 和 popup.html 两个文件。

4.2 manifest.json 清单文件

manifest.json 是插件的配置文件，声明了插件的基本信息、权限和入口资源。

{
// 清单文件版本，Manifest V3 固定为 3
"manifest_version": 3,
// 插件名称，显示在工具栏和商店中
"name": "Hello World",
// 插件版本号，遵循语义化版本规范
"version": "1.0.0",
// 插件功能描述，显示在商店和扩展管理页
"description": "一个最简单的 Chrome 插件示例",
// 工具栏图标点击后弹出的页面
"action": {
// 弹窗页面路径，相对于插件根目录
"default_popup": "popup.html",
// 弹窗默认标题，鼠标悬停时显示
"default_title": "Hello World"
}
}

4.3 popup.html 弹窗页面

popup.html 是点击工具栏图标后弹出的页面，使用标准 HTML 编写界面。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>Hello World</title>
<style>
body {
width: 200px;
padding: 16px;
font-family: sans-serif;
text-align: center;
}
h1 {
font-size: 18px;
color: #333;
}
p {
font-size: 14px;
color: #666;
}
</style>
</head>
<body>
<h1>Hello World!</h1>
<p>这是我的第一个 Chrome 插件</p>
</body>
</html>

4.4 加载与运行

• 加载插件：在 chrome://extensions 开启开发者模式，点击「加载已解压的扩展程序」，选择 hello-world 目录。
• 运行效果：点击工具栏图标，弹出 Hello World 页面。
• 调试技巧：在弹窗页面右键选择「检查」，使用 DevTools 查看日志和调试代码。

5. 内容脚本与页面交互

内容脚本（content script）可以读取和修改网页 DOM，是插件与页面交互的主要方式。下面通过一个完整示例，演示如何在 manifest.json 中静态声明 content script，并在 content.js 中实现网页关键词高亮功能。

5.1 manifest.json 中的 content_scripts 配置

在 manifest.json 中通过 content_scripts 字段声明脚本注入的时机、匹配的页面以及需要注入的 CSS 和 JS 文件。

{
"manifest_version": 3,
"name": "关键词高亮插件",
"version": "1.0.0",
"description": "在网页中自动高亮指定关键词",
"content_scripts": [
{
// 匹配所有 http 和 https 页面
"matches": ["https://*/*", "http://*/*"],
// 注入的 CSS 文件，用于定义高亮样式
"css": ["content.css"],
// 注入的 JS 文件，实现高亮逻辑
"js": ["content.js"],
// 注入时机：document_idle 表示页面 DOM 加载完成后执行
"run_at": "document_idle",
// 是否只在主框架中注入，false 表示所有 iframe 也注入
"all_frames": false
}
]
}

5.2 content.js 实现关键词高亮

content.js 遍历页面文本节点，将匹配到的关键词用 span 包裹并添加高亮样式。为避免重复处理，使用 data 属性标记已处理过的节点。

// 需要高亮的关键词列表
const KEYWORDS = ["Chrome", "插件", "扩展"];
// 高亮样式类名，与 content.css 中定义保持一致
const HIGHLIGHT_CLASS = "keyword-highlight";
/**
判断节点是否已被处理过，避免重复高亮
@param {Node} node – 文本节点
@returns {boolean} 是否已处理
*/
function isProcessed(node) {
return node.parentElement && node.parentElement.dataset.highlighted === "true";
}
/**
将文本节点中匹配的关键词替换为带高亮样式的 span
@param {Text} textNode – 需要处理的文本节点
*/
function highlightTextNode(textNode) {
// 已处理或非文本节点则跳过
if (isProcessed(textNode) || textNode.nodeType !== Node.TEXT_NODE) {
return;
}
const text = textNode.nodeValue;
// 使用正则匹配所有关键词（忽略大小写）
const regex = new RegExp((${KEYWORDS.join("|")}), "gi");
const matches = text.match(regex);
// 没有匹配到关键词则直接返回
if (!matches) {
return;
}
// 创建文档片段，用于批量替换节点
const fragment = document.createDocumentFragment();
let lastIndex = 0;
// 遍历所有匹配结果，拆分文本并插入高亮 span
text.replace(regex, (match, …args) => {
const matchIndex = args[args.length – 2];
// 插入匹配位置之前的普通文本
if (matchIndex > lastIndex) {
fragment.appendChild(document.createTextNode(text.slice(lastIndex, matchIndex)));
}
// 创建高亮 span
const span = document.createElement("span");
span.className = HIGHLIGHT_CLASS;
span.textContent = match;
fragment.appendChild(span);
lastIndex = matchIndex + match.length;
return match;
});
// 插入剩余文本
if (lastIndex < text.length) {
fragment.appendChild(document.createTextNode(text.slice(lastIndex)));
}
// 用文档片段替换原文本节点，并标记为已处理
const parent = textNode.parentNode;
parent.replaceChild(fragment, textNode);
parent.dataset.highlighted = "true";
}
/**
遍历页面所有文本节点并执行高亮
*/
function highlightPage() {
// 使用 TreeWalker 遍历所有文本节点
const walker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_TEXT,
{
acceptNode: (node) => {
// 跳过 script、style 等标签内的文本
const parentTag = node.parentElement?.tagName;
if (["SCRIPT", "STYLE", "NOSCRIPT"].includes(parentTag)) {
return NodeFilter.FILTER_REJECT;
}
return NodeFilter.FILTER_ACCEPT;
}
}
);
const textNodes = [];
while (walker.nextNode()) {
textNodes.push(walker.currentNode);
}
// 逐个处理文本节点
textNodes.forEach(highlightTextNode);
}
// 页面加载完成后执行高亮
highlightPage();

5.3 content.css 定义高亮样式

content.css 为高亮关键词定义醒目的背景色，让用户一眼就能看到匹配结果。

/* 关键词高亮样式 */
.keyword-highlight {
background-color: #ffe58f; /* 淡黄色背景 */
color: #d4380d; /* 深红色文字 */
border-radius: 2px; /* 圆角 */
padding: 0 2px; /* 左右内边距 */
font-weight: bold; /* 加粗显示 */
}

以上示例完整展示了 content script 的配置与实现：manifest.json 负责声明注入规则，content.js 负责遍历 DOM 并高亮关键词，content.css 负责定义高亮样式。刷新目标网页后，页面中所有匹配的关键词都会被自动高亮。

6. 后台脚本与消息通信机制

后台脚本（background）负责管理插件生命周期、处理全局事件和跨页面逻辑。在 Manifest V3 中，后台脚本以 Service Worker 形式运行，通过 chrome.runtime 提供的消息 API 与 popup、content script 进行通信。下面给出完整的消息通信实战代码示例。

6.1 popup 向 background 发送消息

popup 页面通过 chrome.runtime.sendMessage 向 background 发送一次性消息，并接收 background 的回复。

// popup.js
// 点击按钮时向 background 发送消息
document.getElementById("sendBtn").addEventListener("click", () => {
// 发送一次性消息，第一个参数是消息内容，第二个参数是回调函数
chrome.runtime.sendMessage(
{ type: "GREETING", payload: "你好，background！" },
(response) => {
// 接收 background 的回复
console.log("收到 background 回复：", response);
document.getElementById("result").textContent = response.reply;
}
);
});

6.2 content script 向 background 发送消息

content script 同样使用 chrome.runtime.sendMessage 向 background 发送消息，常用于把网页中的用户操作或数据上报给后台处理。

// content.js
// 监听页面上的点击事件，将选中文本发送给 background
document.addEventListener("mouseup", () => {
const selection = window.getSelection().toString().trim();
if (!selection) {
return;
}
// 向 background 发送消息，携带选中文本
chrome.runtime.sendMessage(
{ type: "SELECTED_TEXT", payload: selection },
(response) => {
// 处理 background 的回复
console.log("content 收到回复：", response);
}
);
});

6.3 background 使用 chrome.runtime.onMessage 监听并回复

background 通过 chrome.runtime.onMessage 监听来自 popup 和 content script 的消息，并根据消息类型做出响应。注意回调函数中必须调用 sendResponse 返回结果，否则发送方无法收到回复。

// background.js（Service Worker）
// 监听所有来自 popup 和 content script 的消息
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
console.log("background 收到消息：", message);
console.log("消息来源：", sender);
// 根据消息类型分别处理
if (message.type === "GREETING") {
// 回复 popup 发送的问候消息
sendResponse({ reply: "你好，popup！已收到你的消息。" });
} else if (message.type === "SELECTED_TEXT") {
// 处理 content script 上报的选中文本
const text = message.payload;
// 这里可以调用翻译 API 或其他业务逻辑
sendResponse({ reply: `已收到选中文本：${text}` });
} else {
// 未知消息类型，返回默认回复
sendResponse({ reply: "未知消息类型" });
}
// 返回 true 表示使用异步方式回复，sendResponse 会在稍后调用
return true;
});

6.4 使用 chrome.runtime.connect 建立长连接

当需要多次往返通信时，可以使用 chrome.runtime.connect 建立长连接。连接建立后，双方通过 port.postMessage 发送消息，通过 port.onMessage 接收消息，通信结束后调用 port.disconnect 关闭连接。

// popup.js 或 content.js 中建立长连接
// 建立与 background 的长连接，name 用于标识连接用途
const port = chrome.runtime.connect({ name: "chat-channel" });
// 向 background 发送消息
port.postMessage({ type: "HELLO", payload: "建立长连接" });
// 监听 background 发来的消息
port.onMessage.addListener((message) => {
console.log("长连接收到消息：", message);
});
// 监听连接断开事件
port.onDisconnect.addListener(() => {
console.log("长连接已断开");
});
// 通信结束后主动关闭连接
// port.disconnect();

// background.js 中监听长连接
// 监听来自 popup 或 content script 的长连接请求
chrome.runtime.onConnect.addListener((port) => {
console.log("收到长连接：", port.name);
// 向连接方发送消息
port.postMessage({ reply: "长连接已建立" });
// 监听连接方发来的消息
port.onMessage.addListener((message) => {
console.log("长连接收到消息：", message);
// 回复消息
port.postMessage({ reply: `已收到：${message.payload}` });
});
// 监听连接断开事件
port.onDisconnect.addListener(() => {
console.log("长连接已断开");
});
});

以上示例完整展示了 Chrome 插件中三种常见的消息通信方式：一次性消息（sendMessage）、消息监听与回复（onMessage）、长连接（connect）。实际开发中，一次性消息适合请求-响应模式，长连接适合需要持续双向通信的场景，例如实时数据推送或长时间任务进度上报。

7. 数据存储与设置页面

插件需要持久化用户配置或业务数据时，可以使用 chrome.storage API。它提供了 local 和 sync 两种存储区域，并支持 get、set、remove 等读写操作，以及 onChanged 事件监听数据变化。下面给出完整的代码示例。

7.1 存储类型：local 与 sync 的区别

chrome.storage.local 将数据保存在本地，容量较大（默认 10MB），适合存储业务数据；chrome.storage.sync 会将数据同步到用户登录的 Chrome 账号，容量较小（默认 100KB，单条 8KB），适合存储用户偏好设置。两者 API 完全一致，只需替换命名空间即可。

7.2 chrome.storage 读写操作（Promise 写法）

在 Manifest V3 中，chrome.storage 的 get、set、remove 方法都支持 Promise 写法，配合 async/await 可以让代码更清晰。下面给出完整的读写示例。

// storage.js
// 存储键名常量，便于统一管理
const STORAGE_KEYS = {
THEME: "theme", // 主题色
FONT_SIZE: "fontSize", // 字号
ENABLED: "enabled" // 是否启用
};
/**
写入数据：chrome.storage.set
使用 Promise 写法，写入完成后返回
@param {Object} items – 要写入的键值对对象
*/
async function saveSettings(items) {
try {
// set 接收一个对象，内部会合并到现有数据中
await chrome.storage.sync.set(items);
console.log("设置已保存：", items);
} catch (error) {
console.error("保存设置失败：", error);
}
}
/**
读取数据：chrome.storage.get
传入键名数组，返回包含这些键的对象
@param {string[]} keys – 要读取的键名数组
@returns {Promise} 读取到的数据对象
*/
async function loadSettings(keys) {
try {
// get 接收键名数组，返回 { key: value } 形式的结果
const result = await chrome.storage.sync.get(keys);
console.log("读取到的设置：", result);
return result;
} catch (error) {
console.error("读取设置失败：", error);
return {};
}
}
/**
删除数据：chrome.storage.remove
传入键名或键名数组，删除对应数据
@param {string|string[]} keys – 要删除的键名
*/
async function clearSettings(keys) {
try {
// remove 接收单个键名或键名数组
await chrome.storage.sync.remove(keys);
console.log("已删除设置：", keys);
} catch (error) {
console.error("删除设置失败：", error);
}
}
// 使用示例
async function demo() {
// 写入三条配置
await saveSettings({
[STORAGE_KEYS.THEME]: "dark",
[STORAGE_KEYS.FONT_SIZE]: 14,
[STORAGE_KEYS.ENABLED]: true
});
// 读取全部配置
const settings = await loadSettings([
STORAGE_KEYS.THEME,
STORAGE_KEYS.FONT_SIZE,
STORAGE_KEYS.ENABLED
]);
console.log("当前主题：", settings[STORAGE_KEYS.THEME]);
// 删除主题配置
await clearSettings(STORAGE_KEYS.THEME);
}
demo();

7.3 options_page 设置页面实现

通过 manifest.json 中的 options_page 字段声明设置页面，用户可以在扩展管理页点击「详细信息」进入配置界面。下面给出完整的 HTML 和 JS 实现。

{
"manifest_version": 3,
"name": "设置页面示例",
"version": "1.0.0",
"description": "演示 options_page 设置页面",
// 声明设置页面路径，相对于插件根目录
"options_page": "options.html",
// 声明 storage 权限，才能使用 chrome.storage API
"permissions": ["storage"]
}

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>插件设置</title>
<style>
body {
font-family: sans-serif;
max-width: 480px;
margin: 40px auto;
padding: 0 16px;
}
.field {
margin-bottom: 20px;
}
label {
display: block;
margin-bottom: 6px;
font-weight: bold;
}
select, input[type="number"] {
width: 100%;
padding: 6px;
font-size: 14px;
}
button {
padding: 8px 20px;
font-size: 14px;
cursor: pointer;
}
#status {
margin-top: 12px;
color: #52c41a;
font-size: 13px;
}
</style>
</head>
<body>
<h1>插件设置</h1>
<div class="field">
<label for="theme">主题色</label>
<select id="theme">
<option value="light">浅色</option>
<option value="dark">深色</option>
</select>
</div>
<div class="field">
<label for="fontSize">字号（px）</label>
<input type="number" id="fontSize" min="10" max="24" value="14" />
</div>
<button id="saveBtn">保存设置</button>
<p id="status"></p>
<script src="options.js"></script>
</body>
</html>

// options.js
// 页面加载时读取已保存的设置并回显到表单
document.addEventListener("DOMContentLoaded", async () => {
// 读取存储中的设置，未保存时使用默认值
const result = await chrome.storage.sync.get({
theme: "light", // 默认浅色主题
fontSize: 14 // 默认字号 14px
});

// 将读取到的值回显到表单控件
document.getElementById("theme").value = result.theme;
document.getElementById("fontSize").value = result.fontSize;
});

// 点击保存按钮时写入设置
document.getElementById("saveBtn").addEventListener("click", async () => {
// 收集表单当前值
const settings = {
theme: document.getElementById("theme").value,
fontSize: parseInt(document.getElementById("fontSize").value, 10)
};

// 写入 chrome.storage.sync
await chrome.storage.sync.set(settings);

// 显示保存成功提示，2 秒后自动消失
const status = document.getElementById("status");
status.textContent = "设置已保存";
setTimeout(() => {
status.textContent = "";
}, 2000);
});

7.4 使用 chrome.storage.onChanged 监听数据变化

当存储数据被修改时，chrome.storage.onChanged 事件会触发。它可以在 background、popup 或 content script 中监听，常用于多页面间同步状态。下面给出监听示例。

// background.js 或 popup.js 中监听
// 监听存储数据变化，changes 对象包含所有发生变化的键
chrome.storage.onChanged.addListener((changes, areaName) => {
// areaName 表示变化的存储区域："local" 或 "sync"
console.log("存储区域：", areaName);
// 遍历所有发生变化的键
for (const [key, { oldValue, newValue }] of Object.entries(changes)) {
console.log(键 ${key} 发生变化：);
console.log("旧值：", oldValue);
console.log("新值：", newValue);
// 根据键名执行对应逻辑
if (key === "theme") {
// 主题变化时，通知 content script 更新页面样式
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) =&gt; {
if (tabs[0]) {
chrome.tabs.sendMessage(tabs[0].id, {
type: "THEME_CHANGED",
theme: newValue
});
}
});
}

if (key === "fontSize") {
// 字号变化时，更新弹窗中的显示
console.log("新字号：", newValue);
}
}
});

以上示例完整覆盖了 chrome.storage 的核心用法：local 与 sync 的选型、get/set/remove 的 Promise 写法、options_page 设置页面的完整实现，以及 onChanged 事件监听。实际开发中，建议将存储键名统一管理，并在设置页面保存后通过 onChanged 通知其他页面即时刷新，从而保持插件各模块状态一致。

8. 实战项目：网页划词翻译插件

综合前面所学，开发一个完整的划词翻译插件，覆盖选词、请求、展示全流程。下面给出完整的 manifest.json、content.js 和 content.css 代码示例，并标注关键字段的注释说明。

8.1 manifest.json 权限配置

划词翻译插件需要访问翻译接口，因此必须在 manifest.json 中声明 host_permissions 权限。同时需要声明 content_scripts 注入规则，让 content script 在目标页面中运行。

{
"manifest_version": 3,
"name": "划词翻译插件",
"version": "1.0.0",
"description": "选中网页文字，弹出翻译结果气泡",
// 声明访问翻译接口的域名权限
"host_permissions": [
// Google Translate 免费接口域名
"https://translate.googleapis.com/*"
],
"content_scripts": [
{
// 匹配所有 http 和 https 页面
"matches": ["https://*/*", "http://*/*"],
// 注入的 CSS 文件，定义气泡样式
"css": ["content.css"],
// 注入的 JS 文件，实现划词翻译逻辑
"js": ["content.js"],
// 注入时机：document_idle 表示页面 DOM 加载完成后执行
"run_at": "document_idle",
// 是否只在主框架中注入，false 表示所有 iframe 也注入
"all_frames": false
}
]
}

8.2 content.js 实现划词翻译

content.js 监听鼠标选中事件，获取选中文本后调用翻译 API，并将结果渲染为气泡展示在页面中。下面给出完整的实现代码，包含异常处理逻辑。

// content.js
// 翻译结果气泡的 DOM 元素引用
let bubble = null;
// 防抖定时器，避免频繁触发翻译请求
let debounceTimer = null;
// 上次选中的文本，用于避免重复翻译相同内容
let lastSelectedText = "";

/**
创建翻译结果气泡
@param {string} text – 翻译后的文本
@param {number} x – 气泡左上角 x 坐标
@param {number} y – 气泡左上角 y 坐标
*/
function createBubble(text, x, y) {
// 如果气泡已存在，先移除旧气泡
if (bubble) {
bubble.remove();
}
// 创建气泡容器
bubble = document.createElement("div");
bubble.id = "translate-bubble";
// 气泡样式由 content.css 统一定义，这里只设置位置
bubble.style.left = `${x}px`;
bubble.style.top = `${y}px`;
// 设置气泡内容
bubble.textContent = text;
// 添加关闭按钮
const closeBtn = document.createElement("span");
closeBtn.className = "translate-bubble-close";
closeBtn.textContent = "×";
closeBtn.addEventListener("click", () => {
bubble.remove();
bubble = null;
});
bubble.appendChild(closeBtn);
// 将气泡添加到页面
document.body.appendChild(bubble);
}

/**
调用 Google Translate 免费接口进行翻译
@param {string} text – 需要翻译的文本
@returns {Promise} 翻译结果字符串
*/
async function translateText(text) {
// 构建请求 URL，使用 translate.googleapis.com 免费接口
const url = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=zh-CN&dt=t&q=${encodeURIComponent(text)}`;
// 发起请求
const response = await fetch(url);
// 检查响应状态，非 2xx 抛出错误
if (!response.ok) {
throw new Error(`翻译请求失败：HTTP ${response.status}`);
}
// 解析 JSON 响应
const data = await response.json();
// 提取翻译结果，data[0] 是翻译片段数组
const translated = data[0].map((segment) => segment[0]).join("");
return translated;
}

/**
处理鼠标选中事件
@param {MouseEvent} event – 鼠标事件对象
*/
function handleMouseUp(event) {
// 获取选中文本并去除首尾空白
const selection = window.getSelection().toString().trim();
// 无选中文本时，隐藏气泡并返回
if (!selection) {
if (bubble) {
bubble.remove();
bubble = null;
}
return;
}
// 选中文本与上次相同，不重复翻译
if (selection === lastSelectedText) {
return;
}
lastSelectedText = selection;
// 清除之前的防抖定时器
clearTimeout(debounceTimer);
// 设置防抖，300ms 后执行翻译，避免频繁触发
debounceTimer = setTimeout(async () => {
// 计算气泡显示位置，跟随鼠标
const x = event.clientX + 10;
const y = event.clientY + 10;
try {
// 调用翻译 API
const translated = await translateText(selection);
// 渲染翻译结果气泡
createBubble(translated, x, y);
} catch (error) {
// 网络失败或接口异常时，显示错误提示
console.error("翻译失败：", error);
createBubble("翻译失败，请检查网络连接后重试。", x, y);
}
}, 300);
}

// 监听鼠标选中事件
document.addEventListener("mouseup", handleMouseUp);
// 监听点击事件，点击页面其他区域时隐藏气泡
document.addEventListener("click", (event) => {
// 点击气泡内部时不隐藏
if (bubble && !bubble.contains(event.target)) {
bubble.remove();
bubble = null;
}
});

8.3 content.css 定义气泡样式

content.css 为翻译结果气泡定义统一的视觉样式，包括定位、配色、圆角和阴影，让气泡在任意网页中都能清晰展示。

/* 翻译结果气泡样式 */
#translate-bubble {
position: fixed; /* 固定定位，跟随视口 */
z-index: 99999; /* 最高层级，确保显示在最上层 */
max-width: 320px; /* 最大宽度，防止过长文本撑破布局 */
padding: 10px 14px; /* 内边距，让文字与边框保持间距 */
background: #fff; /* 白色背景，保证可读性 */
border: 1px solid #d9d9d9; /* 浅灰色边框 */
border-radius: 6px; /* 圆角 */
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15); /* 阴影，增强立体感 */
font-size: 14px; /* 正文字号 */
line-height: 1.6; /* 行高，提升阅读体验 */
color: #333; /* 深灰色文字 */
word-break: break-word; /* 长单词自动换行 */
}

/* 关闭按钮样式 */
.translate-bubble-close {
position: absolute; /* 绝对定位到气泡右上角 */
top: 4px;
right: 8px;
cursor: pointer; /* 鼠标悬停显示手型 */
font-size: 16px;
color: #999; /* 灰色，弱化视觉干扰 */
}

/* 关闭按钮悬停效果 */
.translate-bubble-close:hover {
color: #333; /* 悬停时加深颜色，提示可点击 */
}

8.4 异常处理说明

上述代码对以下边界情况做了处理：

• 无选中文本：鼠标选中事件触发时，先检查选中文本是否为空，为空则直接隐藏气泡并返回，避免发起无效请求。
• 网络失败：调用翻译接口时使用 try/catch 捕获异常，网络断开或接口不可用时，在气泡中显示错误提示，而不是静默失败。
• 重复翻译：通过 lastSelectedText 记录上次选中的文本，相同内容不重复请求，减少不必要的网络开销。
• 频繁触发：使用防抖机制，300ms 内的连续选中事件只触发一次翻译请求，避免高频操作导致接口被限流。

以上示例完整展示了划词翻译插件的核心实现：manifest.json 声明 host_permissions 权限和 content_scripts 注入规则，content.js 监听鼠标选中事件、调用 Google Translate 免费接口、渲染结果气泡，content.css 定义气泡样式，并对网络失败、无选中文本等边界情况做了完善的异常处理。加载插件后，在任意网页选中文字即可看到翻译结果气泡。

9. 调试、测试与性能优化

高质量的插件需要经过充分调试和优化，才能稳定运行。

• 调试工具：background 页面、content script 的 DevTools 使用。
• 常见问题：跨域请求、CSP 限制、内存泄漏排查。
• 性能优化：减少 DOM 操作、合理使用缓存、避免阻塞主线程。
• 兼容性：Manifest V2 与 V3 的差异及迁移注意事项。

10. 打包与发布到 Chrome 应用商店

开发完成后，将插件打包并提交到 Chrome 网上应用商店。

• 打包方式：生成 .crx 文件或直接上传源码目录。
• 商店账号：注册 Chrome Web Store 开发者账号并支付一次性费用。
• 提交审核：填写描述、截图、隐私政策，等待审核。
• 更新维护：版本升级、用户反馈处理与数据统计。

12. 常见问题与排查

在 Chrome 插件开发过程中，开发者经常会遇到一些典型问题。下面针对 5 个高频问题，分别给出原因分析和解决方案，并附上代码示例或配置修改说明。

12.1 content script 未注入

问题现象：刷新页面后，content script 中的代码没有执行，页面 DOM 没有被修改。

原因分析：常见原因包括 matches 匹配规则不覆盖当前页面、manifest.json 中未声明 content_scripts、或者插件修改后没有重新加载。

解决方案：检查 manifest.json 中的 matches 是否覆盖目标页面，并确认 content_scripts 配置正确。修改后需要在 chrome://extensions 页面点击「刷新」按钮重新加载插件。

{
"manifest_version": 3,
"name": "content script 排查示例",
"version": "1.0.0",
"content_scripts": [
{
// 确保 matches 覆盖目标页面，例如只匹配 example.com
"matches": ["https://example.com/*"],
"js": ["content.js"],
"run_at": "document_idle"
}
]
}

12.2 消息发送无响应

问题现象：popup 或 content script 调用 chrome.runtime.sendMessage 后，回调函数一直没有触发，收不到 background 的回复。

原因分析：background 的 onMessage 监听器没有调用 sendResponse，或者监听器返回了 false 导致消息通道提前关闭。此外，如果 background 是异步处理消息，必须返回 true 才能保持通道打开。

解决方案：确保 onMessage 回调中调用 sendResponse，并在需要异步回复时返回 true。

// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === "ASYNC_TASK") {
// 异步处理，例如调用 API
fetch("https://api.example.com/data")
.then((res) => res.json())
.then((data) => {
// 异步完成后调用 sendResponse
sendResponse({ success: true, data });
});
// 返回 true 表示使用异步方式回复，保持消息通道打开
return true;
}
// 同步回复
sendResponse({ success: false });
});

12.3 storage 数据不同步

问题现象：在 options 页面保存设置后，popup 或 content script 读取到的数据仍然是旧值。

原因分析：不同页面读取的是同一份 chrome.storage 数据，但可能因为未监听 onChanged 事件，导致页面没有及时刷新；或者误用了 local 和 sync 两个不同的存储区域。

解决方案：统一使用同一个存储区域，并在需要实时同步的页面监听 chrome.storage.onChanged 事件。

// popup.js 或 content.js 中监听数据变化
chrome.storage.onChanged.addListener((changes, areaName) => {
// 只处理 sync 区域的变化
if (areaName === "sync" && changes.theme) {
// 数据变化时立即更新界面
document.body.style.backgroundColor = changes.theme.newValue;
}
});

12.4 跨域请求失败

问题现象：content script 中调用 fetch 请求第三方接口时，浏览器报错 CORS 或请求被拦截。

原因分析：content script 运行在页面上下文中，受页面 CSP 和 CORS 限制。跨域请求应放在 background（Service Worker）中发起，因为 background 不受页面 CSP 限制，只需在 manifest.json 中声明 host_permissions。

解决方案：将请求逻辑迁移到 background，content script 通过消息把请求参数发给 background，由 background 发起 fetch。

{
"manifest_version": 3,
"name": "跨域请求示例",
"version": "1.0.0",
// 声明需要访问的接口域名
"host_permissions": ["https://api.example.com/*"],
"background": {
"service_worker": "background.js"
}
}

// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === "FETCH_DATA") {
// 在 background 中发起跨域请求，不受页面 CSP 限制
fetch(message.url)
.then((res) => res.json())
.then((data) => sendResponse({ success: true, data }))
.catch((error) => sendResponse({ success: false, error: error.message }));
return true;
}
});

12.5 插件加载报错

问题现象：在 chrome://extensions 加载插件时，页面提示「清单文件缺失或不可读」或「无法加载扩展程序」。

原因分析：常见原因包括 manifest.json 语法错误（如缺少逗号、引号不匹配）、引用了不存在的文件（如 background.js 路径错误）、或者 manifest_version 字段缺失。

解决方案：使用 JSON 校验工具检查 manifest.json 语法，确认所有引用的文件路径正确，并确保 manifest_version 为 3。

{
// 必须声明 manifest_version，MV3 固定为 3
"manifest_version": 3,
"name": "加载报错排查示例",
"version": "1.0.0",
"description": "检查 manifest.json 语法和文件路径",
// 确认 background.js 文件确实存在于插件目录中
"background": {
"service_worker": "background.js"
},
// 确认 action 引用的 popup.html 文件存在
"action": {
"default_popup": "popup.html"
}
}

以上 5 个问题是 Chrome 插件开发中最常见的坑。遇到问题时，建议先打开 chrome://extensions 页面查看错误提示，再结合 DevTools 的 Console 面板定位具体原因，通常都能快速解决。

11. 总结与进阶方向

本文从环境准备到发布上线，完整走通了 Chrome 插件开发的流程。后续可以继续探索以下方向：

• 高级 API：chrome.omnibox、chrome.contextMenus、chrome.devtools。
• 框架集成：使用 React/Vue 构建复杂插件界面。
• 自动化测试：为插件编写单元测试和端到端测试。
• 开源实践：阅读优秀开源插件的源码，学习工程化组织方式。

以上内容完整覆盖了 Chrome 插件开发的核心知识点，从环境准备、清单文件配置，到内容脚本、消息通信、数据存储，再到实战项目与发布流程，帮助读者系统掌握插件开发全流程。

建议读者在掌握基础后，结合真实业务场景动手实践，并持续关注 Chrome 官方文档与社区最佳实践，不断提升插件开发能力。