Web Dev for Beginners：从入门代码到 Edge 安装——构建 Carbon Trigger 浏览器扩展完整指南

本文基于 Web-Dev-For-Beginners 仓库第 5 模块的浏览器扩展入门代码（Carbon Trigger 扩展）展开，覆盖从环境准备、webpack 构建，到在 Edge 中加载未打包扩展、配置 CO2 Signal API 密钥与区域代码的完整流程，并结合仓库中的参考实现源码剖析"碳强度彩色圆点"的实现原理。读完后你将能够独立完成一个可运行、可加载、可配置的浏览器扩展，并理解其背后的数据请求与本地存储机制。

一、项目定位：一个监控区域电网碳强度的小扩展

Carbon Trigger 是 Web Dev for Beginners 课程"Building a browser extension"模块的实战项目。它的核心功能是：调用 tmrow 的 CO2 Signal API 查询某个电网区域当前的电力碳强度与化石燃料发电占比，并将结果直接展示在浏览器扩展栏——通过一个颜色深浅变化的圆点，提醒你所在区域当前的用电"绿色程度"。这样你就可以基于这一实时信息，判断当前是否适合执行高耗电活动（例如原文给出的例子：在区域电网碳强度高时推迟烘干衣物）。

这个"圆点"视觉概念来源于面向加州排放数据的 Energy Lollipop 扩展。整个项目被设计成"迷你网站"形态的浏览器扩展：一个面向极具体任务定制的小型 Web 应用，可在 Edge、Chrome、Firefox 上运行。模块整体的三大主题为：

• 1-about-browsers：浏览器工作原理与扩展基础；
• 2-forms-browsers-local-storage：表单、浏览器存储；
• 3-background-tasks-and-performance：后台任务与性能。

本文聚焦的是该模块的入门代码说明（start 目录），也就是从零构建并安装这个扩展的实操路径。

二、环境准备与项目依赖

入门代码位于 5-browser-extension/start 目录，要求如下：

• 已安装 npm（Node.js 包管理器）；
• 将 start 目录代码复制/下载到你电脑上的一个本地文件夹。

从 package.json 可以确认项目声明的运行环境要求：

"engines": {
    "npm": ">=9.0.0",
    "node": ">=18.0.0"
}

即 Node.js 需不低于 18.0.0、npm 不低于 9.0.0，这也是本文所有命令的适用前提。

同一份 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"
}

可以推断出几点关键信息：

• 项目名为 carbon-trigger-extension（v1.0.0），采用 MIT 协议；
• 构建完全由 webpack 驱动：npm run build 实际执行的就是 webpack 命令，npm run watch 则是开启监听模式的增量构建，适合开发时边改边构建；
• 运行时唯一的外部依赖是 axios（HTTP 请求库），用于在扩展中调用 CO2 Signal API；
• test 脚本目前是占位实现，说明本入门代码未附带测试用例，验证手段是"构建后装入浏览器实测"。

三、安装依赖与构建扩展

在 start 目录（或你本地复制的对应文件夹）中依次执行：

# 安装所有必需包（webpack、webpack-cli、axios）
npm install

# 用 webpack 构建扩展产物
npm run build

npm install 会根据 package.json 与 package-lock.json 安装全部依赖；npm run build 通过 webpack 把 src/index.js 打包成浏览器可直接加载的扩展文件。构建产物会输出到 dist 目录——这个目录正是下一步安装扩展时要选中的目标文件夹。

一个值得注意的细节是：入门代码中的 src/index.js 并不是空白文件，而是一份带编号注释的"实现骨架"，它规定了你需要按顺序完成的功能点：

//1
// form fields
// results divs

//6
//call the API

//5
//set up user's api key and region

//4
// handle form submission

//3 initial checks

//2
// set listeners and start app

注释编号即课程的动手顺序：先准备表单字段与结果容器（1），再写初始化检查（3）、表单提交处理（4）、API 密钥与区域配置（5）、API 调用（6），最后挂载监听器并启动应用（2）。完整实现可对照 solution/src/index.js 参考。

四、在 Edge 中加载未打包扩展（Load Unpacked）

构建完成后，按以下步骤把扩展装入 Edge：

1. 点击浏览器右上角的"三个点"菜单，找到扩展（Extensions）面板；
2. 如果尚未开启，先打开左下角的开发者模式（Developer mode）；
3. 选择 Load unpacked（加载未打包扩展）；
4. 在弹出的目录选择框中选择构建生成的 dist 文件夹，扩展即被加载。

补充两点来自课程正文的提示：

• 开发期间每改一次代码，流程是"重新 npm run build → 回到扩展面板点击 reload 重新加载"，而不是重复 Load unpacked；
• Load unpacked 是开发者自测安装方式；已发布扩展则应从各浏览器官方商店安装，两者不能混用（详见 1-about-browsers 中"Production Extension Installation"一节）。

五、配置 API 密钥与区域代码

扩展加载后，要真正使用它还需要两样东西：

1. CO2 Signal API 密钥：在 CO2 Signal 官方网站的订阅框中填写你的邮箱即可获取（入门文档以链接形式给出获取入口，此处不再重复外部地址）。请求时该密钥以 auth-token 请求头的形式发送；
2. 区域代码：对应 Electricity Map 电网分区编码。例如波士顿所在电网的代码是 US-NEISO。区域代码列表可在 electricitymap 的 zones API 中查到。

在扩展弹出的设置界面中填入 API 密钥与区域代码后，浏览器扩展栏的彩色圆点会随之改变颜色，反映你所在区域当前的用电碳强度，从而为"现在适不适合做高耗电的事"提供直观参考。

六、实现剖析：圆点颜色是怎么算出来的

对照仓库中的参考实现 solution/src/index.js，可以把上述"填密钥 → 圆点变色"的行为拆成四个可验证的实现环节：

1. 数据请求：axios 调用 CO2 Signal 的 latest 接口

await axios
    .get('https://api.co2signal.com/v1/latest', {
        params: { countryCode: region },
        headers: { 'auth-token': apiKey },
    })

请求返回后取出 data.carbonIntensity（碳强度，克 CO2/千瓦时）与 data.fossilFuelPercentage（化石燃料发电占比），并做了空值校验——任一字段缺失即抛出错误，落入 catch 分支显示"Sorry, data unavailable for the selected region."（见 solution/src/index.js）。

2. 颜色分档：五档碳强度刻度

let co2Scale = [0, 150, 600, 750, 800];
let colors = ['#2AA364', '#F5EB4D', '#9E4229', '#381D02', '#381D02'];

实现取与当前碳强度最接近的刻度值，再映射到对应颜色（见 solution/src/index.js）：绿色 #2AA364 表示很清洁，越往深棕色越表示化石电力占比高。这就是扩展栏圆点"变色"的完整逻辑。

3. 通知背景脚本更新图标

chrome.runtime.sendMessage({ action: 'updateIcon', value: { color: closestColor } });

页面脚本通过 chrome.runtime.sendMessage 把目标颜色发给 background 脚本，由后者更新扩展图标（见 solution/src/index.js）。初始化时还会先发送一个 color: 'green' 的默认值（见 solution/src/index.js）。这一"popup 发消息、background 改图标"的分工正是第 3 课"Background tasks and performance"要讲解的核心模式。

4. 用 localStorage 记住配置，实现"一次填写、长期有效"

const setUpUser = async (apiKey, region) => {
    localStorage.setItem('apiKey', apiKey);
    localStorage.setItem('region', region);
    ...
    displayCarbonUsage(apiKey, region);
};

init() 启动时先读 localStorage 中的 apiKey 与 region：若存在则直接隐藏表单、拉取数据展示结果；若缺失则显示配置表单（见 solution/src/index.js）。另有"Change region"按钮，点击后调用 localStorage.removeItem('region') 并重新初始化，允许更换区域（见 solution/src/index.js）。

七、小结与后续路径

回顾全文，入门代码给出的完整工作流是：确认 Node/npm 版本 → 复制 start 代码到本地 → npm install → npm run build（webpack 产出 dist）→ 在 Edge 开发者模式下 Load unpacked 选择 dist → 填入 CO2 Signal API 密钥与区域代码（如 US-NEISO）→ 观察扩展栏圆点随区域碳强度变色。

如果你想继续深入，建议按模块顺序学习：

• 浏览器与扩展基础：manifest、popup、background 等结构，以及开发/发布两种安装方式的区别；
• 表单与本地存储：本文第五、六节中表单提交与 localStorage 持久化的课程化讲解；
• 后台任务与性能：updateIcon 背后的 background 脚本机制与扩展性能考量；
• 完整参考实现：solution 目录中可运行的成品代码。

需要注意的限制：本文所有构建与安装步骤均以当前仓库 start/solution 目录中的 package.json（Node ≥ 18、npm ≥ 9、webpack 5）为准；CO2 Signal API 与 Electricity Map 区域代码均来自外部服务，实际可用性取决于对方服务的开放策略。