Coding Train《Programming with Text》11.3 实战:用 Chrome 扩展 Content Script 修改任意网页
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 文件,但有两个关键特征:
- 运行上下文是网页:脚本被注入到某个匹配的页面中执行,与页面共享同一个 DOM,因此可以直接通过
documentAPI 查找元素、修改样式、替换内容。 - 由扩展清单声明注入规则:扩展通过
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 扩展的标准开发流程运行:
- 打开 Chrome,在地址栏访问
chrome://extensions; - 打开右上角"开发者模式"开关;
- 点击"加载已解压的扩展程序",选择上述目录;
- 访问
https://shiffman.net(该站点早已不在,仅作为原课程演示目标;在本地验证时可将matches改为自己要测试的域名,如http://localhost/*或<all_urls>); - 打开开发者工具(F12)查看 Console,应看到
Chrome extension go?日志,页面上所有段落背景变为品红。
课程文档头部标注 live_example: false,即本课没有线上可交互示例,效果必须通过本地加载扩展来观察。
matches 匹配模式进阶:从单一站点到所有网址
本课示例只对 shiffman.net 生效,而实际扩展通常需要覆盖更广的范围。仓库中其他示例展示了更宽的匹配方式:
- 11-04 背景脚本示例的 manifest.json 使用
<all_urls>匹配所有网址,同时增加了background与browser_action字段,是 content script 与 background script 并存的完整结构; - CC_082 Ex-kitten-sion 的 manifest.json 同样使用
<all_urls>; - CC_083 p5 扩展的 manifest.json 也使用
<all_urls>。
<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);
}
关键点有二:
- 内容脚本在网页上下文运行,但可以调用少量
chrome.*API,例如这里的chrome.extension.getURL(file),它把扩展包内的相对路径解析成chrome-extension://开头的完整 URL; - 要让页面(或 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 通信的两种典型形态:
- background → content:后台脚本用
chrome.tabs.sendMessage(tab.id, msg)定向发送到指定标签页的内容脚本; - content → background:内容脚本用
chrome.runtime.sendMessage(msg)广播给扩展的其他监听者。
内容脚本的运行环境与限制
结合仓库源码,可以把 content script 的约束归纳为三点:
- DOM 共享、JS 隔离:content script 与页面共享 DOM(所以能
getElementsByTagName并改样式),但运行在与页面隔离的脚本环境中,不能直接访问页面自己的 JavaScript 变量或函数。仓库所有示例都只通过 DOM API 与事件系统与页面交互,正是这一边界的体现; - 扩展资源默认不可见:内容脚本要加载扩展内部图片等资源,必须先在 manifest 声明
web_accessible_resources(见 CC_082 实例),否则chrome-extension://请求会被拒绝; - 远程脚本受 CSP 约束:扩展页面默认只允许
'self'来源的脚本,如需从 CDN 加载库(如 p5),必须在 MV2 的content_security_policy中显式放行(见 CC_084 与 11-06 示例)。
此外,内容脚本与页面同生命周期:页面刷新或跳转后脚本重新注入。若需要在浏览器启动即运行、跨页面保持状态,则要借助 background script(见 11-04 背景脚本)。
小结与进一步阅读
本课把 Chrome 扩展开发的"地基"讲清楚了:一个 manifest.json 声明注入规则,一个 content.js 在页面上下文中操作 DOM,两者结合即可实现"在指定网页上自动执行任意 DOM 操作"的能力。从它出发,可以继续沿着第 11 章学习完整的扩展能力矩阵:
- 11.4 背景脚本:浏览器级事件监听;
- 11.5 弹窗(Pop-ups) 与 11.6 弹窗消息通信:popup 与 content script 通过消息 API 交换数据;
- 11.7 新标签页覆盖:扩展覆盖浏览器内置页面;
- 11.8 跨浏览器扩展:同一套清单与脚本迁移到 Firefox 等浏览器,其 manifest.json 与 Chrome 版本几乎一致。
实战扩展方面,session11 目录的 README 列出了本课直接对应的三个 Coding Challenge:CC_082(图片替换)、CC_083(p5 绘制层)、CC_084(划词查词),它们共同构成了从"理论最小示例"到"完整可用扩展"的渐进路线。动手建议:先加载本课的两文件示例观察注入效果,再依次阅读三个挑战项目的 manifest 与脚本,重点对比它们的 matches、web_accessible_resources、消息 API 用法差异,就能建立起对 content script 开发模式的完整直觉。