Chrome扩展安全开发从零到一 - 完整教学文档

一、Chrome扩展基础理论

1.1 浏览器兼容性

• 基于Chromium内核的浏览器(Chrome、新版Edge、Opera、Brave)可通用大部分API
• Firefox v57+通过WebExtensions API实现兼容，需少量修改即可运行
• 不同浏览器API文档：
  • Chrome: https://developer.chrome.com/extensions/api_index
  • Opera: https://dev.opera.com/extensions/apis
  • Edge: https://learn.microsoft.com/zh-cn/microsoft-edge/extensions-chromium/developer-guide/api-support
  • Firefox: https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions

1.2 技术架构

• 基于网页技术(HTML、JavaScript和CSS)
• 在沙盒执行环境中运行
• 两种主要架构：
  • Manifest V2 (当前主流)
  • Manifest V3 (未来方向)

1.3 Manifest版本时间线

• V1已在Chrome v18后弃用
• V2淘汰计划：
  • 2022.6: 停止公开V2扩展上架
  • 2023.1(Chrome v112): 开发版停止支持
  • 2023.6(Chrome v115): 稳定版停止支持
  • 2024.1: 完全移除V2支持

二、Manifest V2开发实战

2.1 基本结构

• 必须文件：manifest.json(根目录)
• 可选文件：JS、HTML、CSS、图片等资源

2.2 manifest.json详解

{
  "name": "扩展名称",
  "author": "作者",
  "version": "版本号",
  "manifest_version": 2,
  "description": "描述",
  "icons": {
    "16": "图标路径",
    "64": "图标路径"
  },
  "background": {
    "persistent": true,
    "scripts": ["后台脚本路径"]
  },
  "browser_action": {
    "default_title": "悬停提示",
    "default_icon": "图标路径",
    "default_popup": "弹出页面路径"
  },
  "permissions": [
    "API权限",
    "http://*/*",
    "https://*/*"
  ],
  "content_security_policy": "CSP策略"
}

2.3 后台脚本(background)

• 角色：服务端逻辑
• 配置方式：
  • page: 指定HTML页面
  • scripts: 指定JS文件(与page互斥)
  • persistent: 是否持续运行
• 全局变量注意事项：
  • persistent: false时变量不可靠
  • 可使用chrome.storage保存数据

示例：

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    title: "菜单项",
    id: "menuId"
  });
});

2.4 用户界面

• browser_action:
  • 始终显示的工具栏图标
  • 配置弹出页面(popup)
• page_action:
  • 条件显示的工具栏图标
  • 通过API控制显示条件
• popup页面特点：
  • 点击外部时关闭
  • 关闭时销毁所有元素和变量

2.5 前端框架集成

Vue集成方式：

1. 脚手架方式：

   • 使用Vite或Webpack构建
   • 配置输出目录到扩展文件夹
   • 推荐使用nodemon监控自动构建

2. CDN/本地引入：

   • 需修改CSP允许unsafe-eval

   "content_security_policy": "script-src 'self' 'unsafe-eval';"
   

2.6 Chrome API调用

API分类：

1. 自定义扩展用户界面
   • browserAction, commands, contextMenus等
2. 扩展实用工具
   • accessibility, background, storage等
3. 浏览器操作
   • bookmarks, downloads, tabs等
4. 网络相关
   • webRequest, cookies, declarativeContent等

调用步骤：

1. 在permissions中声明权限
2. 调用API方法

示例(拦截请求)：

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return { cancel: true }; },
  { urls: ["*://dnslog.cn/*"] },
  ["blocking"]
);

2.7 调试方法

1. 加载扩展：

   • 访问chrome://extensions/
   • 开启开发者模式
   • 加载解压的扩展文件夹

2. 调试popup：

   • 右键popup → 检查
   • 保持popup打开状态调试

3. 调试background：

   • 通过扩展页面链接跳转
   • 后台页面URL格式：chrome-extension://[扩展ID]/_generated_background_page.html

2.8 内容脚本注入

两种注入方式：

1. 声明式注入(manifest.json配置)：

"content_scripts": [{
  "matches": ["http://*.example.com/*"],
  "css": ["styles.css"],
  "js": ["contentScript.js"]
}]

2. 编程式注入(需activeTab权限)：

// 注入代码
chrome.tabs.executeScript({
  code: 'document.body.style.backgroundColor="orange"'
});

// 注入文件
chrome.tabs.executeScript({
  file: 'contentScript.js'
});

访问页面JS对象：

const script = document.createElement('script');
script.src = chrome.runtime.getURL("content.js");
document.documentElement.appendChild(script);

2.9 脚本通信

1. popup与background通信

// popup获取background对象
chrome.extension.getBackgroundPage().method();

// background获取popup对象
chrome.extension.getViews({type: "popup"})[0].method();

2. 内容脚本与扩展通信

单向消息：

// 内容脚本发送
chrome.runtime.sendMessage({greeting: "hello"}, function(response) {
  console.log(response.farewell);
});

// 扩展接收
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  if (request.greeting == "hello") 
    sendResponse({farewell: "goodbye"});
});

长连接通信：

// 建立连接
var port = chrome.runtime.connect({name: "channel"});

// 发送消息
port.postMessage({message: "test"});

// 接收消息
port.onMessage.addListener(function(msg) {
  console.log(msg);
});

安全注意事项：

• 验证消息来源
• 过滤消息内容
• 避免直接执行消息中的代码

三、Manifest V3迁移指南

3.1 主要变更

1. manifest.json变更：

   • manifest_version: 3
   • background → service_worker
   • browser_action/page_action → action
   • 新增host_permissions
   • CSP改为对象形式

2. Service Worker：

   • 替代background脚本
   • 无DOM访问权限
   • 必须使用fetch()代替XMLHttpRequest
   • 全局变量不持久

3. API变更：

   • webRequestBlocking → declarativeNetRequest
   • 移除多个废弃API

3.2 常见坑点

1. 定时任务：

   • 不能使用setTimeout/setInterval
   • 改用alarms API

2. 网络请求拦截：

   • 规则数量有限制
   • 灵活性降低

3. eval限制：

   • 禁止动态执行代码
   • 影响部分JS框架

3.3 迁移示例

V2 background:

// 后台持续运行的脚本
var globalData = {};

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  // 处理逻辑
});

V3 Service Worker:

// 使用storage保存数据
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  chrome.storage.local.get(['data'], function(result) {
    // 处理逻辑
    chrome.storage.local.set({data: newData});
  });
});

// 使用alarms代替定时器
chrome.alarms.create('refresh', {periodInMinutes: 60});
chrome.alarms.onAlarm.addListener(function(alarm) {
  if (alarm.name === 'refresh') {
    // 定时任务
  }
});

四、安全开发最佳实践

1. CSP策略：

   • 最小化权限原则
   • 谨慎使用unsafe-inline和unsafe-eval

2. 消息验证：

   • 验证消息来源(sender)
   • 过滤消息内容

3. 敏感操作：

   • 用户确认后再执行
   • 记录关键操作日志

4. 数据存储：

   • 敏感数据加密存储
   • 使用chrome.storage代替全局变量

5. 权限管理：

   • 仅申请必要权限
   • 运行时请求可选权限

五、完整开发流程

1. 规划功能需求
2. 设计manifest结构
3. 实现后台逻辑(background/service worker)
4. 开发用户界面(popup/options)
5. 实现内容脚本(如需)
6. 测试各组件通信
7. 安全审计
8. 打包发布

六、资源参考

1. Chrome扩展官方文档：

   • MV2: https://developer.chrome.com/docs/extensions/mv2/
   • MV3: https://developer.chrome.com/docs/extensions/mv3/

2. 中文文档：

   • https://doc.yilijishu.info/chrome/intro.html

3. 已知问题：

   • https://developer.chrome.com/docs/extensions/mv3/known-issues/

4. 迁移指南：

   • https://developer.chrome.com/docs/extensions/mv3/mv3-migration/