Coding Train《Programming with Text》11.3 实战:用 Chrome 扩展 Content Script 修改任意网页

原创2026-10-13 22:06:561,746 阅读
文章标签:教程文档示例工程

Coding Train《Programming with Text》11.3 实战:用 Chrome 扩展 Content Script 修改任意网页

本篇文章基于 Coding Train(The Coding Train)《Programming with Text》系列课程第 11.3 集《Content Scripts》及其配套示例仓库整理而成。你将理解 Chrome 扩展中 content script 的核心运行机制——它是一段注入到网页上下文中的 JavaScript,可以在页面加载后直接读取并修改 DOM——并通过一个"把网页所有段落背景染成品红"的最小示例,掌握从 manifest.json 配置到脚本编写、再到本地加载验证的完整流程。文章还会结合本仓库中多个真实扩展实例(替换图片的 Ex-kitten-sion、注入 p5.js 绘制层的扩展、划词查词扩展等),展示 content script 与 background script、popup 之间的协作方式。

本课在课程中的位置

本课属于 Programming with Text 课程索引 中"Chrome Extensions"章节(第 11 章)的第三集。课程前两集分别是:

  • 11.1 扩展简介:介绍 Chrome 扩展的整体概念与若干真实扩展案例;
  • 11.2 Bookmarklets:介绍书签小脚本——一种通过浏览器书签按钮手动触发 JavaScript 来修改页面内容的方式。

Bookmarklet 与 content script 的对比是理解本课的关键:bookmarklet 需要用户主动点击书签才执行一次,而 content script 由扩展在 manifest 中声明"在哪些网址上自动注入",浏览器按匹配规则替你在页面加载时执行脚本,无需任何手动操作。仓库中配套的书签脚本示例 bookmarklet.js 用 IIFE 包裹逻辑、遍历 p 标签并把文字改为 puppy,与本课 content script 的段落染色示例形成了一对很好的对照。

原课程文档 11.3-content-scripts.md 对 content script 的定义非常精炼,全文核心即这一句:

The content script is a JavaScript file that runs in the context of a web page (and can be used to modify that page.)

下文将围绕这一定义,结合配套示例代码逐层展开。

什么是 Content Script:运行在网页上下文里的 JS

content script(内容脚本)是 Chrome 扩展的一种组成部分。它本质上一个普通的 JavaScript 文件,但有两个关键特征:

  1. 运行上下文是网页:脚本被注入到某个匹配的页面中执行,与页面共享同一个 DOM,因此可以直接通过 document API 查找元素、修改样式、替换内容。
  2. 由扩展清单声明注入规则:扩展通过 manifest.json 中的 content_scripts 字段声明"在哪些 URL 上注入哪些 JS 文件",浏览器负责完成注入调度。

与之相对的是 11.4 背景脚本(Background Scripts):background script 运行在浏览器全局环境中,Chrome 启动时即运行,用于监听浏览器级事件(菜单、地址栏、扩展按钮等),它不直接接触某个页面的 DOM。两者的职责边界是第 11 章后续几集反复出现的主题。

最小可运行示例:把页面段落染成品红

本课的配套代码位于 11-03_Chrome_Extensions_Content_Scripts 目录,只有两个文件:manifest.json 与 content.js。它们共同构成了一个完整可加载的最小扩展。

1. manifest.json:声明注入规则

manifest.json 全文如下:

{
  "manifest_version": 2,
  "name": "Coding Train Extension",
  "version": "0.1",
  "content_scripts": [
    {
      "matches": [
        "http://shiffman.net/*",
        "https://shiffman.net/*"
      ],
      "js": ["content.js"]
    }
  ]
}

逐字段解读:

字段 值 含义
manifest_version 2 清单文件版本。仓库中所有示例均基于 MV2,这是 2017 年课程录制时的标准格式;若要在现代 Chrome 上重新加载运行,需要留意 MV2 的兼容性现状,建议以浏览器官方文档为准
name Coding Train Extension 扩展名称,显示在扩展管理页面
version 0.1 扩展版本号,Chrome 要求其为合法版本字符串
content_scripts[].matches http://shiffman.net/*、https://shiffman.net/* 匹配模式(match pattern),决定脚本注入哪些页面
content_scripts[].js ["content.js"] 注入的脚本文件列表,按顺序执行

注意这里 matches 同时列出了 http 与 https 两种协议,确保站点无论以哪种协议访问都会被注入脚本。matches 是 content script 的"触发开关",只有 URL 匹配的页面才会运行脚本。

2. content.js:修改页面 DOM

content.js 是注入到页面后执行的脚本本体:

console.log('Chrome extension go?');

let paragraphs = document.getElementsByTagName('p');
for (elt of paragraphs) {
  elt.style['background-color'] = '#FF00FF';
}

逐行解析:

  • console.log('Chrome extension go?'):在页面控制台打印标记,用于确认脚本已成功注入执行;
  • document.getElementsByTagName('p'):通过标准 DOM API 取到页面中所有 <p> 段落元素——这正体现了 content script"运行在网页上下文、可直接操作 DOM"的特性;
  • for (elt of paragraphs):遍历所有段落(仓库原始代码中 elt 未用 let 声明,会隐式成为全局变量,正式编写时建议补上 let);
  • elt.style['background-color'] = '#FF00FF':把每个段落的背景色改为品红(#FF00FF)。

整个脚本没有任何扩展专有 API,使用的全是普通网页 JavaScript 能力。这正是 content script 的核心价值:你可以用最平凡的 DOM 操作,批量改写任意匹配网页的呈现效果。

3. 加载与验证

本仓库为只读归档,你可以在本地把 Courses/programming_with_text/session11/11-03_Chrome_Extensions_Content_Scripts 目录复制到自己的开发环境中,然后按 Chrome 扩展的标准开发流程运行:

  1. 打开 Chrome,在地址栏访问 chrome://extensions;
  2. 打开右上角"开发者模式"开关;
  3. 点击"加载已解压的扩展程序",选择上述目录;
  4. 访问 https://shiffman.net(该站点早已不在,仅作为原课程演示目标;在本地验证时可将 matches 改为自己要测试的域名,如 http://localhost/* 或 <all_urls>);
  5. 打开开发者工具(F12)查看 Console,应看到 Chrome extension go? 日志,页面上所有段落背景变为品红。

课程文档头部标注 live_example: false,即本课没有线上可交互示例,效果必须通过本地加载扩展来观察。

matches 匹配模式进阶:从单一站点到所有网址

本课示例只对 shiffman.net 生效,而实际扩展通常需要覆盖更广的范围。仓库中其他示例展示了更宽的匹配方式:

<all_urls> 是匹配所有 http/https/file 等常见协议的快捷写法。实际开发中建议遵循最小权限原则:先明确脚本要作用于哪些站点,再决定匹配范围;<all_urls> 适合演示或需要全站生效的场景,但会显著扩大扩展的影响面。

仓库中的进阶 Content Script 实例

第 11 章 session 目录之外,仓库中还有三个与此直接相关的 Coding Challenge 扩展项目,它们展示了 content script 的三种进阶玩法。

实例一:CC_082 "The Ex-Kitten-sion"——替换页面所有图片

kitten.js 演示了 content script 配合 web_accessible_resources 的使用:

let imgs = document.getElementsByTagName('img');

for (let imgElt of imgs) {
  let r = Math.floor(Math.random() * filenames.length);
  let file = 'kittens/' + filenames[r];
  let url = chrome.extension.getURL(file);
  imgElt.src = url;
  console.log(url);
}

关键点有二:

  1. 内容脚本在网页上下文运行,但可以调用少量 chrome.* API,例如这里的 chrome.extension.getURL(file),它把扩展包内的相对路径解析成 chrome-extension:// 开头的完整 URL;
  2. 要让页面(或 content script)能通过该 URL 加载扩展内部资源,必须在 manifest 中声明 web_accessible_resources:"web_accessible_resources": ["kittens/*.jpg"]。这是"扩展资源对网页可见"的显式开关,属于安全机制的一部分。

实例二:CC_083——在任意网页上注入 p5.js 绘制层

CC_083 的 manifest.json 展示了 content script 一个极其实用的能力:在 js 数组中按顺序列出多个文件,把第三方库与业务脚本一起注入页面:

"js": ["p5.js", "p5.dom.js", "sketch.js"]

这意味着库文件先加载,业务脚本随后即可使用 p5 全局对象。注意:从仓库文件列表看,该目录内只保留了 manifest.json 与 sketch.js,p5.js、p5.dom.js 需要在本地自行补齐到同一目录才能运行。对应的 sketch.js 采用 p5 实例模式(instance mode),把画布铺满整个窗口:

  • document.body.style['userSelect'] = 'none' 禁用文字选中,避免拖动画布时选中页面文本;
  • sketch.createCanvas(sketch.windowWidth, sketch.windowHeight) 创建与窗口等大的画布;
  • c.position(0, 0) 将画布定位到页面左上角;
  • c.style('pointer-events', 'none') 是关键技巧:让画布不拦截任何鼠标事件,底层页面依然可正常点击、滚动,画布只负责在上面绘制;
  • sketch.mouseIsPressed 时用 line() 连线绘制,相当于一个覆盖在任意网页上的涂鸦层。

这展示了 content script 的另一种典型用途:不修改页面原有内容,而是在其之上叠加一层可视化/交互元素。

实例三:CC_084 "Word Definition Extension"——划词取词并与后台通信

CC_084 的 content.js 演示了 content script 监听页面事件、再把数据送出页面上下文的完整链路:

window.addEventListener('mouseup', wordSelected);

function wordSelected() {
  let selectedText = window.getSelection().toString().trim();
  console.log(selectedText);
  if (selectedText.length > 0) {
    let message = { text: selectedText };
    chrome.runtime.sendMessage(message);
  }
}

脚本在 mouseup 事件中通过 window.getSelection() 捕获用户划选的文字,随后调用 chrome.runtime.sendMessage(message) 把消息发给扩展的其他部分。对应的 background.js 用 chrome.runtime.onMessage.addListener(receiver) 接收并把选词存入 window.word,供 popup 查询使用。

这揭示了 content script 的关键边界:它生活在网页 DOM 里,却与扩展其他部件隔离。要跨过这道边界交换数据,必须走消息 API(messaging)。该示例的 manifest 还演示了 MV2 下的 content_security_policy 配置——显式放行 https://cdn.jsdelivr.net/npm/p5@1.1.4/lib/p5.min.js,允许 popup 页面从 CDN 加载 p5。

消息传递:让 content script 与扩展其他部件协作

content script 很少单打独斗,通常需要与 background、popup 配合。第 11 章的后几集围绕消息 API 展开,本课内容是其基础:

  • 11-04 的 content.js 展示了"被动收消息"的写法:chrome.runtime.onMessage.addListener(gotMessage),收到 txt === 'hello' 的消息才执行段落染色逻辑;
  • 11-06 Pop-ups Messaging 示例 展示"主动发消息"的完整回路:background.js 在 browserAction.onClicked 回调中构造消息 { txt: 'hello' },通过 chrome.tabs.sendMessage(tab.id, msg) 发给当前标签页;content.js 监听后把所有段落 innerHTML 替换为消息文本。该示例的 manifest.json 同时声明了 "permissions": ["tabs"] 与 browser_action(含 default_popup),并再次出现 CSP 配置;
  • 11-07 New Tab Override 与 11-08 跨浏览器扩展 继续扩展这一主题。

从仓库多个示例看,可以归纳出 content script 通信的两种典型形态:

  1. background → content:后台脚本用 chrome.tabs.sendMessage(tab.id, msg) 定向发送到指定标签页的内容脚本;
  2. content → background:内容脚本用 chrome.runtime.sendMessage(msg) 广播给扩展的其他监听者。

内容脚本的运行环境与限制

结合仓库源码,可以把 content script 的约束归纳为三点:

  1. DOM 共享、JS 隔离:content script 与页面共享 DOM(所以能 getElementsByTagName 并改样式),但运行在与页面隔离的脚本环境中,不能直接访问页面自己的 JavaScript 变量或函数。仓库所有示例都只通过 DOM API 与事件系统与页面交互,正是这一边界的体现;
  2. 扩展资源默认不可见:内容脚本要加载扩展内部图片等资源,必须先在 manifest 声明 web_accessible_resources(见 CC_082 实例),否则 chrome-extension:// 请求会被拒绝;
  3. 远程脚本受 CSP 约束:扩展页面默认只允许 'self' 来源的脚本,如需从 CDN 加载库(如 p5),必须在 MV2 的 content_security_policy 中显式放行(见 CC_084 与 11-06 示例)。

此外,内容脚本与页面同生命周期:页面刷新或跳转后脚本重新注入。若需要在浏览器启动即运行、跨页面保持状态,则要借助 background script(见 11-04 背景脚本)。

小结与进一步阅读

本课把 Chrome 扩展开发的"地基"讲清楚了:一个 manifest.json 声明注入规则,一个 content.js 在页面上下文中操作 DOM,两者结合即可实现"在指定网页上自动执行任意 DOM 操作"的能力。从它出发,可以继续沿着第 11 章学习完整的扩展能力矩阵:

实战扩展方面,session11 目录的 README 列出了本课直接对应的三个 Coding Challenge:CC_082(图片替换)、CC_083(p5 绘制层)、CC_084(划词查词),它们共同构成了从"理论最小示例"到"完整可用扩展"的渐进路线。动手建议:先加载本课的两文件示例观察注入效果,再依次阅读三个挑战项目的 manifest 与脚本,重点对比它们的 matches、web_accessible_resources、消息 API 用法差异,就能建立起对 content script 开发模式的完整直觉。

登录后查看全文
website-archive