Web-Dev-For-Beginners 浏览器扩展模块 Part 1：理解浏览器原理并搭好第一个扩展的脚手架

本篇基于 Web-Dev-For-Beginners 仓库中 浏览器扩展模块第一讲 的核心内容展开：先厘清浏览器如何把 URL 变成你看到的网页，再讲解扩展（Extension）为何值得动手做，最后完整走一遍仓库中 Carbon Trigger 扩展项目的初始化流程——从 npm run build 打包、在 Edge 中 load unpacked 加载，到在 dist/index.html 里写出配置表单与结果展示区。读完后，你能独立搭建并加载一个可运行的扩展界面骨架，为后续接入 API 与 Local Storage 做好准备。

一、浏览器是什么：从 WorldWideWeb 到现代渲染引擎

浏览器扩展要「附加」在浏览器之上运行，所以动手写代码之前，必须先弄清宿主环境的运作方式。

1.1 一点历史

• 第一个网页浏览器叫 WorldWideWeb，由蒂姆·伯纳斯-李（Sir Timothy Berners-Lee）爵士于 1990 年创建；
• 现代浏览器可以视为「把服务器内容呈现到用户设备上的程序软件」，运行在桌面、笔记本或手机上。

1.2 输入 URL 之后发生了什么

用户通过统一资源定位符（URL，Uniform Resource Locator）上网，URL 通常以 http 或 https 开头，使用超文本传输协议（Hypertext Transfer Protocol）。此时浏览器会：

1. 与 URL 指向的服务器建立通信；
2. 抓取网页的 HTML、CSS 与 JavaScript 资源；
3. 由渲染引擎解析并把内容呈现到用户设备（手机、桌机或笔记本）的屏幕上。

此外浏览器还具备「记忆」能力：

• 缓存内容，不必每次访问都向服务器请求；
• 保存浏览历史与 cookies（包含用户活动信息的小型数据块）。

1.3 各浏览器并不完全一致

这是一个重要的开发前提：各家浏览器的实现并不相同，各有长短。专业的前端开发者必须保证页面在不同浏览器上都能正常工作，包括处理小屏幕视图、离线用户行为等场景。

实操建议：

• 用 caniuse 这类兼容性查询工具核对 Web 技术的浏览器支持情况（仓库文档给出的用法是：构建网页时查询技术支持清单，确保给用户最好的体验）；
• 安装分析工具（analytics）来统计你的用户最常用哪些浏览器，把支持优先级建立在真实数据上。

延伸阅读方向：仓库原文在「复习与自学」中列出了浏览器历史、Web 历史与伯纳斯-李访谈三类资料，可用于深入理解 Web 的起源与设计初衷。

二、为什么写浏览器扩展：以 Carbon Trigger 为例

扩展是附加在浏览器上的小型应用，用来快速、重复地执行某些功能。常见动机举例：

• 需要在网页上检查交互元素的颜色 → 颜色选择器扩展；
• 记不住账号密码 → 密码管理器扩展。

从开发角度看，扩展也是很好的练手项目：它们只管理并执行少量任务，规模小、边界清晰，很适合初学者。

本仓库的浏览器扩展模块（5-browser-extension/README.md）安排了一个贯穿三节课的实战项目：Carbon Trigger 碳足迹扩展。它调用 CO2 Signal 的 API，查询指定地区电网的用电结构与碳排放强度，在浏览器工具栏用一个颜色圆点提示「现在适合不适合做高耗电的事」（例如延迟开烘干机）。项目能同时跑在 Edge、Chrome 与 Firefox 上。

三、安装与加载扩展：标准开发流程

在开发自己的扩展之前，先熟悉「建制 + 加载」这个循环。各浏览器管理扩展的入口略有差异，以 Edge 为例（Chrome 与 Firefox 思路相似）：

1. 运行 npm run build 建制（打包）你的扩展；
2. 在浏览器工具栏的扩展区，点击右上角「更多设置」（三点菜单）；
3. 打开扩展管理页（edge://extensions）；
4. 新扩展：选择 load unpacked（加载已解压的扩展），从本地选择打包产物目录（本项目为 dist 文件夹）；
5. 已安装扩展：点击该扩展卡片上的 reload 按钮重新加载。

注意：开发/测试自己的扩展时，通常还需要开启「开发者模式」（developer mode）。若要安装已公开发布的扩展，则直接去浏览器官方扩展商店即可，不需要上述 sideload 流程。

四、展开行动：项目准备与目录结构

本节对应原文档「展开行动」章节。开始前你需要准备：

• 一组 CO2 Signal 的 API key：在 CO2 Signal 官网填写邮箱获取；
• 一个 电力区域代码（zone code）：来自 Electricity Map 的 zones 数据（例如波士顿使用 US-NEISO）；
• 起始代码：仓库内的 start 文件夹，需要修改其中的代码文件；
• NPM：Node 的包管理工具，本地安装的软件包会记录在 package.json 中，成为网页可使用的资源。

4.1 start 项目的真实结构

对照仓库中 5-browser-extension/start 的实际内容，文档里给出的结构可以这样理解：

5-browser-extension/start/
├── dist/                 # 打包产物目录，即 load unpacked 时要选的目录
│   ├── manifest.json     # 扩展清单（已给出默认配置）
│   ├── index.html        # 弹窗界面 HTML
│   ├── background.js     # 背景脚本（service worker）
│   ├── main.js           # 由 webpack 打包生成的 JS
│   ├── styles.css        # 界面样式
│   └── images/           # 界面图片（如 plants-people.png）
├── src/
│   └── index.js          # 你的 JS 源码，会被打包进 dist/main.js
├── package.json          # 依赖与脚本定义
└── package-lock.json

从 package.json 可以看到项目的工程约束与脚本定义：

配置项	值	含义
scripts.build	webpack	npm run build 即执行 webpack 打包
scripts.watch	webpack --watch	开发时监听源码变化自动重新打包
engines.node	>=18.0.0	要求 Node 18 及以上
engines.npm	>=9.0.0	要求 npm 9 及以上
devDependencies	webpack ^5.105.0、webpack-cli ^5.1.4	打包工具链，仅开发期需要
dependencies	axios ^1.15.0	运行期依赖，后续课程用它发起 API 请求

4.2 manifest.json 里已经写好了什么

start/dist/manifest.json 已经给出了一份 Manifest V3 的默认清单，值得逐个字段看懂：

{
    "manifest_version": 3,
    "name": "My Carbon Trigger",
    "version": "0.1.0",
    "host_permissions": ["<all_urls>"],
    "background": {
        "service_worker": "background.js"
    },
    "action": {
        "default_popup": "index.html"
    }
}

• manifest_version: 3：声明使用 Chrome 扩展的 Manifest V3 规范（Edge 同样兼容该格式）；
• background.service_worker：MV3 下背景逻辑运行在 service worker 中，这里指向 dist/background.js；
• action.default_popup：点击工具栏图标时弹出 index.html，这就是我们要填表单和结果区的页面；
• host_permissions: ["<all_urls>"]：为了让扩展跨域请求 CO2 Signal 的 API 而预置的权限。

从源码结构看，src/index.js 目前只有一组带编号的注释占位（//1 表单字段引用、//2 设置监听并启动、//4 处理表单提交、//6 调用 API 等），是为后续课程留出的代码骨架——第一讲只需要把它「原样打包」即可。

五、为扩展编写 HTML：配置表单与结果展示区

dist/index.html 中预留了两个注释占位：<!--form area--> 与 <!--result area-->。本讲的任务就是把这两块填上内容。

5.1 配置表单（form area）

在 <!--form area--> 处加入输入区域，收集「区域代码 + API Key」：

<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>
</button>
</form>

原文档代码中的按钮写法为 <button class="search-btn">Submit</button>；表单的作用是把用户输入的信息存下来，后续课程会把它写入 Local Storage 持久化。

5.2 结果展示区（result area）

紧跟在 </form> 之后（即 <!--result area--> 处）新增结果容器：

<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>

这些占位 div/span 各自承担明确职责（后续课程会用 JS 填充）：loading 显示加载态、errors 显示错误信息、data 存放原始数据、result-container 呈现格式化结果、clear-btn 允许更换地区重新配置。

六、安装依赖并首次建制：npm install 与 webpack

HTML 就位后，执行：

npm install

该命令依据 package.json 安装 webpack 等开发依赖。然后：

npm run build

Webpack 会把 src/index.js 编译打包成 dist/main.js。此时打开 dist/main.js 可以看到「打好包」的产物。随后按第三节的流程，把 dist 目录 load unpacked 进 Edge（或 Chrome），就能看到扩展完整呈现：欢迎标题 + 你刚写的表单与结果区。

到此，浏览器扩展开发的第一步完成。下一步（第二讲）将给静态表单接上真正的「生命力」：读取 Local Storage、处理表单提交、调用 CO2 Signal API 并渲染数据。

七、挑战与后续作业

• 挑战：逛一逛浏览器扩展商店，安装一套扩展功能到你的浏览器中。开发者可以检查它的文件结构——看看一个真实发布的扩展由哪些文件组成（对照本项目的 manifest.json、index.html、background.js、main.js 会更直观）。
• 作业：重新造型你的套件——为扩展编写自定义 CSS，围绕配色、字体、间距与交互反馈完成一版属于自己的视觉设计，并对照可访问性要求自检。

八、本讲小结

能力点	本讲掌握内容
浏览器原理	URL → HTTP(S) 抓取 → 渲染呈现；缓存、历史、cookies；浏览器差异与兼容性检查
扩展加载流程	npm run build → 扩展管理页 → load unpacked（首次）/ reload（更新）
项目工程	Manifest V3 清单字段含义；webpack 打包链（build/watch 脚本）；Node ≥ 18 / npm ≥ 9 环境要求
界面骨架	在 start/dist/index.html 的 <!--form area-->、<!--result area--> 处写入配置表单与结果容器

完成以上步骤后，你的扩展已经具备可加载的完整界面；API 调用、Local Storage 持久化与背景脚本的性能优化，都将在 Forms and local storage 与 Background tasks and performance 两讲中继续展开。