Web-Dev-For-Beginners 浏览器扩展课程第 1 课：从浏览器架构出发搭建碳足迹扩展界面

2026-09-07 10:03:47作者：侯霆垣

本篇文章围绕开源教学仓库 Web-Dev-For-Beginners 中「浏览器扩展项目」的第 1 课展开，系统讲解浏览器如何解析 URL、渲染网页，浏览器扩展（Browser Extension）的架构与分类，以及如何亲手为「区域碳排放追踪扩展（Carbon Footprint / Carbon Trigger Extension）」搭建配置表单与结果展示的 HTML 界面。学完本篇，你将掌握从"输入 URL 到页面呈现"的完整链路、现代浏览器的核心组件、扩展的开发与加载流程，并能在本地用 Webpack 完成一次可运行的扩展界面原型构建。

背景：这一课在整个浏览器扩展项目中的位置

Web-Dev-For-Beginners 课程的 5-browser-extension 模块以"构建一个可在 Edge、Chrome、Firefox 上运行的浏览器扩展"为主线，目标产物是一个根据 CO2 Signal API 查询指定区域电力碳强度的迷你应用。整个模块分为三个循序渐进的教学单元：

本课的任务定位非常清晰：先搞清楚浏览器本身是怎么工作的（扩展的运行底座），再动手搭出扩展的第一个可见界面。正如发明电话前亚历山大·贝尔必须先理解声音的传播原理，写扩展之前先理解浏览器架构，才能让你的扩展与浏览器既有系统无缝协作。

一、浏览器是什么：一台复杂的"文档解释器"

Web 浏览器本质上是一台精密的文档解释器。当你在地址栏输入 google.com 并回车，浏览器会发起一系列复杂操作——向遍布全球的服务器请求内容，再把这些代码解析、渲染成你眼前可交互的网页。

这个流程与世界上第一个浏览器 WorldWideWeb 的设计一脉相承：1990 年，蒂姆·伯纳斯-李（Tim Berners-Lee）创造它正是为了让超链接文档能够被所有人访问。

✅ 历史小知识：第一个浏览器名为 "WorldWideWeb"，由蒂姆·伯纳斯-李爵士于 1990 年创建。

以这张浏览器信息图（sketchnote）可以直观地看到"输入 URL 后浏览器内部发生了什么"：

从 URL 到网页：一次请求经历的五步

从按下回车到看到网页，浏览器在数秒内协同完成多个环节。你可以按下面这个链路理解它：

翻译（DNS 解析）：把人类可读的 URL 通过 DNS 查询翻译成服务器的 IP 地址；
建连（HTTP/HTTPS）：通过 HTTP 或 HTTPS 协议与 Web 服务器建立安全连接；
请求：向服务器请求特定的网页内容；
接收：收到服务器的 HTML 标记、CSS 样式和 JavaScript 代码；
渲染：把所有内容渲染成你看到的可交互网页。

下面用时序图还原了这一过程，注意其中两处标注了 Extension（扩展） 的环节——这正是浏览器为扩展预留的"请求生命周期"介入点：

sequenceDiagram
    participant User
    participant Browser
    participant Extension
    participant DNS
    participant Server

    User->>Browser: 输入 URL 并回车
    Browser->>Extension: 触发 beforeRequest 事件
    Extension->>Extension: 检查 URL 是否需要改写
    Browser->>DNS: 查询服务器 IP
    DNS->>Browser: 返回 IP 地址
    Browser->>Server: 请求网页内容
    Server->>Browser: 返回 HTML、CSS、JavaScript
    Browser->>Extension: 触发 beforeResponse 事件
    Extension->>Extension: 按需修改响应内容
    Browser->>User: 渲染完整网页
    Extension->>User: 更新扩展 UI

快速自测：你能从头到尾讲出"输入 URL → 看到网页"的路径吗？标准答案是：DNS 查询把 URL 变成 IP → HTTP 请求从服务器取回内容 → 解析处理 HTML/CSS/JavaScript → 渲染展示最终网页 → 扩展可在多个阶段介入并修改内容。

二、现代浏览器的核心组件：扩展的"发力点"在哪里

要决定"扩展往哪里加功能最有效"，先要知道浏览器内部有哪些可被利用的子系统。课程的架构脑图将现代浏览器划分为以下层面：

核心组件（Core Components）：渲染引擎、JavaScript 引擎、网络栈、存储 API；
用户界面（User Interface）：地址栏、标签页管理、书签、扩展图标；
扩展系统（Extension System）：Manifest 清单文件、内容脚本（Content Scripts）、后台页面（Background Pages）、弹出窗口（Popup）；
安全模型（Security Model）：同源策略、权限 API、内容安全、隔离世界（Isolated Worlds）；
开发工具（Development Tools）：DevTools 集成、调试控制台、性能监视器、扩展检查器。

其中每一个子系统的含义与给扩展带来的机会，可以归纳为下表：

浏览器特性	用途	扩展可切入的机会
渲染引擎	展示 HTML、CSS 和 JavaScript	内容修改、样式注入
JavaScript 引擎	执行 JavaScript 代码	自定义脚本、API 交互
本地存储	在本地保存数据	用户偏好、缓存数据
网络栈	处理 Web 请求	请求监控、数据分析
安全模型	保护用户免受恶意内容侵害	内容过滤、安全增强

理解这些特性会带来四方面收益：

帮助你定位扩展最能产生价值的位置；
帮助你为扩展功能挑选正确的浏览器 API；
帮助你设计与浏览器系统高效协作的扩展；
帮助你确保扩展遵循浏览器安全最佳实践。

值得一提的是脑图中安全模型层面的几个概念——同源策略、权限 API、内容安全策略（CSP）与隔离世界——共同构成了扩展的"安全边界"：扩展运行在与网页相互隔离的上下文中，只在获得用户授权（manifest 中的 permissions）后访问特定浏览器能力。这是本课只先建立认知、后续课程再通过 manifest.json 具体实践的要点。

三、跨浏览器开发：同一套扩展，不同浏览器的差异

Chrome、Firefox、Safari 与 Edge 对 Web 标准的实现存在细微差异——如同不同编程语言对同一算法的处理方式不同——这直接影响扩展的开发策略。

跨浏览器扩展开发的关键注意事项：

在 Chrome、Firefox、Edge 上都实际测试你的扩展；
适配不同浏览器的扩展 API 与 manifest 格式差异；
处理各浏览器在性能特征与能力限制上的差异；
为浏览器特有但其他浏览器缺失的功能提供降级方案（fallback）。

关于支持的优先级：你可以通过在自己的 Web 项目中安装分析（analytics）包，来判断目标用户更偏爱哪些浏览器，用数据指导"优先支持哪个浏览器"的决策，而不是盲目平均发力。

四、什么是浏览器扩展：增强浏览器能力的迷你应用

浏览器扩展是增强浏览体验的迷你应用——它把功能直接加到浏览器界面上，用户无需安装独立 App 或切换复杂工作流即可随时使用。这呼应了道格拉斯·恩格尔巴特等早期计算先驱"用技术增强人类能力"的构想：扩展 = 对浏览器基础功能的"增强（augment）"。

从"个人使用 → 专业工具 / 简单 → 复杂"两个维度看，扩展生态大致分为四类象限：

第一象限 · 开发者工具（Developer Tools）：如代码格式化器（Code Formatters）、取色器（Color Pickers）；
第二象限 · 企业级解决方案（Enterprise Solutions）：面向组织的复杂工具；
第三象限 · 个人小工具（Personal Utilities）：如广告拦截器（Ad Blockers）；
第四象限 · 生产力应用（Productivity Apps）：如密码管理器（Password Managers）、笔记应用、时间追踪器。

常见扩展分类及其价值：

生产力工具：任务管理器、笔记应用、时间追踪器，帮助你保持条理；
安全增强类：密码管理器、广告拦截、隐私保护工具，守护你的数据；
开发者工具：代码格式化、取色器、调试工具，让开发流程更顺畅；
内容增强类：阅读模式、视频下载、截图工具，改善浏览体验。

留一个思考题：你最喜欢的浏览器扩展是什么？它解决了哪些具体任务、如何改善你的浏览体验？——在动手写代码前想清楚"扩展到底在增强什么"，会让后面的每个 API 选择都更有依据。

五、扩展的安装与管理：开发加载 vs. 生产安装

浏览器扩展的安装流程在现代浏览器间已高度标准化（只是界面细节不同）。理解安装流程，有助于你预判最终用户安装你的扩展时会获得怎样的体验。

开发阶段的安装流程：写代码 → 构建 → 加载 → 测试

开发与测试自有扩展时，遵循下面这条"循环迭代"工作流：

flowchart TD
    A[编写代码] --> B[构建扩展]
    B --> C{首次安装?}
    C -->|是| D[Load Unpacked 加载解包目录]
    C -->|否| E[Reload 重载扩展]
    D --> F[测试功能]
    E --> F
    F --> G{工作正常?}
    G -->|否| H[调试问题]
    G -->|是| I[面向用户发布]
    H --> A
    I --> J[发布到扩展商店]

Step 1：构建扩展

# 构建你的扩展
npm run build

这条命令实际完成四件事：

编译你的源代码为浏览器可直接加载的文件；
打包 JavaScript 模块为优化后的 bundle；
在 /dist 目录生成最终的扩展文件；
准备好扩展供安装与测试。

以仓库中真实存在的起步工程 package.json 为例，其中定义了两个与构建相关的脚本，可清晰地看到上面这条命令背后的工具链：

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "watch": "webpack --watch",
    "build": "webpack"
},
"devDependencies": {
    "webpack": "^5.105.0",
    "webpack-cli": "^5.1.4"
},
"dependencies": {
    "axios": "^1.15.0"
},
"engines": {
    "npm": ">=9.0.0",
    "node": ">=18.0.0"
}

可以看到：build 实际执行的是 webpack（即 Webpack 打包），并额外提供了 watch 模式（webpack --watch，修改源码后自动重新打包）；axios 依赖则预留给后续课程调用 CO2 Signal API。工程对运行环境也有明确要求：Node.js ≥ 18、npm ≥ 9，动手前请先检查本地版本。

Step 2：进入浏览器扩展管理页

打开浏览器自带的扩展管理页面（如 edge://extensions 或 chrome://extensions）；
点击浏览器右上角的"设置及更多"按钮（... 图标）；
在下拉菜单中选择"扩展"。

Step 3：加载扩展

全新安装：选择 Load unpacked（加载解压缩的扩展），选中你的 /dist 文件夹；
代码更新后：点击已安装扩展旁的 reload 按钮；
为了调试：务必打开 Developer mode（开发者模式），以获得更深的调试能力。

生产环境的扩展安装：三条路径的差别

开发安装（Development installations）：允许你在开发期测试尚未发布的扩展；
商店安装（Store installations）：来自官方商店的经过审核的正式扩展，支持自动更新；
侧载（Sideloading）：从官方商店之外安装扩展，通常要求开启开发者模式。

课程的明确提醒是：上述"开发安装"说明只适用于你自己构建的扩展；面向普通用户分发时应引导他们去官方扩展商店安装（如 Microsoft Edge 加载项商店、Chrome 应用商店等）。

注意：加载自己的扩展时，务必开启开发者模式，并按需允许来自其他商店的扩展，否则 load unpacked 入口可能不可见。

六、实战项目准备：碳足迹追踪扩展的需求清单

本课及后续两课的动手目标，是构建一个展示你所在区域用电碳足迹的浏览器扩展。当你在表单中输入区域代码与 API Key 后，扩展会调用 CO2 Signal API 返回该区域的碳强度与化石燃料占比，从而帮你判断"现在这个时段是否适合做高耗能的事情"（例如在高碳时段推迟使用烘干机）。

按照"做中学"（learning by doing）的思路，先来盘点动手前需要准备的资源：

必须的 API 访问凭据：

CO2 Signal API Key：前往 co2signal.com 输入邮箱即可免费获取；
区域代码（Region Code）：通过 Electricity Map 查询你所在区域的代码，例如波士顿使用 'US-NEISO'（美国新英格兰 ISO 电网区域）。

开发工具：

Node.js 与 NPM：安装项目依赖的包管理工具；
起步代码 start 目录：课程提供了起步工程作为开发基线。

在仓库中，起步代码的真实形态是 5-browser-extension/start 目录：其中 package.json 已配好 Webpack 构建脚本与依赖（上文已展示），而 start/src/index.js 目前只是一个带编号注释的"脚手架占位文件"，按顺序标出了后续要填充的六个实现点：

//1
// form fields          —— 表单字段
// results divs         —— 结果区域 div

//6
//call the API          —— 调用 CO2 Signal API

//5
//set up user's api key and region   —— 设置用户的 API Key 与区域

//4
// handle form submission            —— 处理表单提交

//3 initial checks                   —— 初始检查

//2
// set listeners and start app       —— 绑定监听器并启动应用

这个占位文件恰好预告了整套扩展的完整实现路径：绑监听器启动 → 初始检查 → 处理表单提交 → 存储 Key 与区域 → 调用 API → 更新表单/结果 UI，其中 "初始检查、表单提交、本地存储" 属于第 2 课，"调用 API、更新 UI"属于第 3 课的范畴。

目标项目结构：每个文件各自扮演什么角色

课程的完整扩展包含下面这些文件（dist 是构建产物，本课只涉及其中 UI 相关的 index.html）：

project-root/
├── dist/                    # 构建后的扩展文件
│   ├── manifest.json        # 扩展配置（元数据/权限/入口）
│   ├── index.html           # 用户界面标记
│   ├── background.js        # 后台脚本功能
│   └── main.js              # 编译后的 JavaScript bundle
├── src/                     # 源码开发文件
│   └── index.js             # 你的主要 JavaScript 代码
├── package.json             # 项目依赖与脚本
└── webpack.config.js        # 构建配置

各文件职责一览：

manifest.json：定义扩展的元数据、权限与各入口点——这是扩展的"身份证 + 权限清单"；
index.html：创建用户点击扩展图标时出现的界面 UI；
background.js：处理后台任务与浏览器事件监听（第 3 课重点）；
main.js：构建流程完成后的最终打包产物；
src/index.js：存放最终被编译进 main.js 的主要开发代码；
package.json：声明依赖与 build/watch 脚本。

结合仓库实际情况需要补充一点：起步代码（start 目录）当前只提交了 src/index.js、package.json 与 package-lock.json，没有附带独立的 webpack.config.js 或现成的 dist/——也就是说，dist/ 下的 manifest.json、index.html、background.js 等文件正是在课程学习中按步骤构建出来的产物。npm run build 会依据 Webpack 的约定式入口 src/index.js 进行打包，默认输出到 dist/，与上图中"src/index.js 编译为 dist/main.js"的映射一致。

两条贯穿全程的重要提醒：

组织建议：把 API Key 和区域代码存到安全的笔记里，开发过程中会反复用到这两个值；
安全红线：绝不把 API Key 或敏感凭据提交进代码仓库——后续步骤会演示如何安全地管理它们。

七、搭建扩展界面：配置表单 + 结果展示的双视图设计

扩展界面采用双视图设计：首次使用时的"配置视图（Setup View）"，与展示数据时的"结果视图（Results View）"。这种"渐进式披露（progressive disclosure）"设计原则可以避免一次性向用户倾倒过多信息——先把必要信息按逻辑顺序逐层呈现。

配置视图 —— 首次使用时的表单：

结果视图 —— 展示碳足迹数据：

7.1 构建配置表单

配置表单负责在首次使用时采集用户数据；配置完成后，这些信息将被持久化到浏览器存储中供后续会话使用。在你的扩展 dist/index.html 中，加入如下表单结构：

<form class="form-data" autocomplete="on">
    <div>
        <h2>New? Add your Information</h2>
    </div>
    <div>
        <label for="region">Region Name</label>
        <input type="text" id="region" required class="region-name" />
    </div>
    <div>
        <label for="api">Your API Key from tmrow</label>
        <input type="text" id="api" required class="api-key" />
    </div>
    <button class="search-btn">Submit</button>
</form>

这段表单设计的可取之处：

语义化结构：label for 与 input id 一一对应，保证可访问性与可点击区域；
浏览器自动完成：autocomplete="on" 让浏览器辅助用户填写；
强制必填：required 属性确保两个字段都填写后才能提交；
便于样式与脚本定位：region-name、api-key、search-btn 等描述性类名，为后续 CSS 样式与 JavaScript 事件绑定提供了清晰的挂钩点；
明确的用户引导：Region Name、Your API Key from tmrow 等标签让首次配置的用户一目了然。

7.2 构建结果展示区

紧接表单之下，添加用于展示碳足迹数据的区域。这块 HTML 划分出"加载中 / 错误 / 调试数据 / 正式结果 / 重配"等多个状态层：

<div class="result">
    <div class="loading">loading...</div>
    <div class="errors"></div>
    <div class="data"></div>
    <div class="result-container">
        <p><strong>Region: </strong><span class="my-region"></span></p>
        <p><strong>Carbon Usage: </strong><span class="carbon-usage"></span></p>
        <p><strong>Fossil Fuel Percentage: </strong><span class="fossil-fuel"></span></p>
    </div>
    <button class="clear-btn">Change region</button>
</div>

各结构单元的作用：

loading：在 API 数据拉取期间显示加载提示；
errors：API 请求失败或数据非法时展示错误信息；
data：存放原始数据，方便开发期调试（正式展示并不使用它）；
result-container：以格式化排版向用户呈现 my-region（区域）、carbon-usage（碳用量）、fossil-fuel（化石燃料占比）三项指标；
clear-btn：允许用户更换区域、重新配置扩展（也就是从结果视图切回配置视图的开关）。

注意：这些 span 当前都是空元素，具体数值会在后续课程中由 JavaScript 调用 CO2 Signal API 后写入——本课只负责把"骨架 UI"立起来。

八、打通构建链路：npm install 与 Webpack 打包

HTML 就位后，需要安装项目依赖并验证构建流程：

npm install

这一步会完成：

下载 package.json 中声明的 Webpack 及其他开发依赖；
配置面向现代 JavaScript 的编译工具链；
准备好扩展构建与测试所需的开发环境；
启用代码打包、优化与跨浏览器兼容能力。

构建过程说明：Webpack 会把 src/index.js 的源码打包到 dist/main.js。该过程会对代码做面向生产的优化，并处理浏览器兼容问题。当你在 package.json 中看到 "watch": "webpack --watch" 脚本时，意味着开发期可以开启监听模式，改动源码后自动重建，省去手动反复执行 npm run build 的麻烦。

现阶段验收清单

完成上述步骤后，按下面顺序验证你的成果：

运行构建命令编译代码（npm run build）；
以开发者模式把扩展加载进浏览器（Load unpacked → 选中 dist 目录）；
确认表单能正确显示且外观专业；
检查所有表单元素的对齐与可用性。

到这一步，你实际已经做到：

搭好扩展的基础 HTML 结构；
创建了带语义标记的配置界面与结果界面；
建立了使用行业标准工具（NPM + Webpack）的现代开发工作流；
打好了后续添加交互式 JavaScript 功能的地基。

本课核心自测题（动手进入下一课前请确认）：

你能解释项目结构中每个文件的用途吗？
你理解构建流程如何转换你的源码吗？
为什么要把"配置"与"结果"拆成两个独立的 UI 区块？（提示：渐进式披露 + 状态分离）
表单结构如何同时满足易用性与可访问性？

开发工作流层面，你现在应当能够：修改扩展界面的 HTML/CSS → 运行构建命令编译改动 → 在浏览器中 reload 扩展验证更新 → 借助浏览器开发者工具调试问题。

九、安全与体验进阶练习

课程内置挑战：给表单加校验与反馈

在正式进入后续课程前，可以先用 Agent 模式完成下面的强化练习，把"用户体验"这门功课补上：

挑战描述：为扩展添加表单校验与用户反馈，改善输入 API Key 与区域代码时的体验。

实现提示：

编写 JavaScript 校验函数：API Key 字段至少 20 个字符；
校验区域代码是否符合规范格式（形如 'US-NEISO'）；
通过输入框边框颜色反馈结果：有效 = 绿色，无效 = 红色；
增加一个"显示 / 隐藏 API Key"的切换按钮，兼顾安全与输入便利。

这套校验逻辑恰好对应 start/src/index.js 中标注的 "3 initial checks（初始检查）" 与 "4 handle form submission（处理表单提交）" 两个占位步骤，你可以在仓库起步代码基础上练习。

课后作业：重新设计你的扩展

课程为这一阶段配套的作业是 Restyle your extension（重新设计你的扩展样式），从分析现有 CSS 出发，经历"配色方案（建议与环境主题呼应并保证对比度）、字体排版、布局与间距"三步定制，最后覆盖表单态 / 加载态 / 结果态 / 错误态逐一测试；作业同时给出了基础 / 中级 / 高级三档创意难度与完整的评分细则（视觉设计、功能性、代码质量、可访问性）。

观察练习（5 分钟版）

打开 Chrome/Edge 扩展页（如 chrome://extensions），看看自己已安装的扩展；
加载网页时打开 DevTools 的 Network 面板，观察网络请求时序；
按 Ctrl+U 查看页面源码，体会 HTML 结构；
在 DevTools 中审查任意元素并实时修改其 CSS。

周期成长清单

本小时可达成：完成测验理解浏览器基础、为扩展创建基本 manifest.json、构建带弹出窗口的简单 "Hello World" 扩展、在开发者模式下测试加载、查阅目标浏览器的扩展文档；
一周目标：交付一个具备真实用途的完整扩展；掌握 content scripts、background scripts、popup 交互；熟练使用 storage、tabs、messaging 等浏览器 API；在多个网站与场景下测试扩展；
一月进阶：制作解决不同问题的多个扩展；学习进阶浏览器 API 与安全最佳实践；参与开源浏览器扩展项目；攻克跨浏览器兼容与渐进增强；成为能帮助他人的扩展开发专家。