Carbon Trigger 浏览器扩展起步指南：基于 CO2 Signal API 监测区域电力碳强度

本篇指南围绕 Web-Dev-For-Beginners 课程「5. 构建浏览器扩展」模块的起步代码（starter code）展开：你将使用 tmrow 提供的 CO2 Signal API 跟踪你所在区域的电力碳强度，构建一个可直接装入 Edge 的浏览器扩展，在浏览器工具栏上用一个彩色圆点实时提示当前区域用电的"碳负载"，从而帮你判断当下是否适合做烘干、充电等高耗电活动。读完并动手完成后，你将掌握 npm 依赖安装、webpack 构建、Edge 以"加载已解压缩的扩展"方式安装扩展、申请 API 密钥与选择区域代码这几项完整的扩展开发实战能力。

项目背景：扩展能做什么

Carbon Trigger 是一个"迷你网站"式的浏览器扩展：它检查 CO2 Signal API 中指定区域的电力使用与碳强度数据，并返回该区域的碳足迹读数。用户只需要在扩展界面里输入一次 API 密钥和区域代码，之后就可以随时（ad hoc）查看本地电力使用情况，让数据反过来影响自己的用电决策。课程给出的典型例子是：在你的区域电力使用处于高位时段，推迟运行烘干机这类高碳活动会更合理。

扩展工具栏上的"彩色圆点"是核心交互：圆点颜色会随区域能源使用强度变化，给你一个直观的提示——哪些高耗能活动此时适合做、哪些最好缓一缓。根据 模块总 README，这套"圆点"图标概念参考了面向加州排放数据的 Energy Lollipop 浏览器扩展的图标结构，而整个"绿色云碳触发器"的创意来自 Microsoft 绿色云倡导团队的 Asim Hussain（该扩展结构还借鉴了 Adebola Adeniran 的 COVID 扩展）。

环境要求与起步准备

起步代码对运行环境有明确的版本约束。从 package.json 中的 engines 字段可以确认：

• npm >= 9.0.0
• Node.js >= 18.0.0

起步代码还声明了两个依赖：运行期依赖 axios（^1.15.0，用于调用 CO2 Signal API），以及开发期依赖 webpack（^5.105.0）与 webpack-cli（^5.1.4）。package.json 中的 keywords 标注了 chrome extension、edge extension、carbon usage tracker，说明这是一份跨 Chromium 系（Edge、Chrome）与 Firefox 可用的扩展起步项目。

准备步骤：

1. 安装 npm（随 Node.js 一同安装即可，注意满足上述版本下限）；
2. 把这份起步代码下载/克隆到电脑上的一个文件夹，即 5-browser-extension/start 目录。

安装依赖与 webpack 构建

进入 5-browser-extension/start 目录后，安装所有必需的包：

npm install

然后用 webpack 构建扩展：

npm run build

对应 package.json 中 scripts 的写法：build 脚本执行 webpack，另外还提供了一个 watch 脚本（webpack --watch），在开发过程中可以开启它让构建随源码变化自动刷新。构建完成后，产物会输出到 dist 目录——这个目录就是下一步装入浏览器的对象。

在 Edge 中安装已解压缩的扩展

Edge 的安装路径如下：

1. 点击浏览器右上角的"三个点"菜单，找到扩展（Extensions）面板；
2. 选择 "Load Unpacked"（加载已解压缩） 来加载一个新扩展；
3. 在弹出的文件选择框中打开构建生成的 dist 文件夹，扩展即被装入。

装入后，扩展会在浏览器扩展栏显示一个彩色圆点图标，等待你在扩展界面中填入 API 密钥与区域代码。

获取 API 密钥与区域代码

扩展要真正工作，需要两样凭据：

• CO2 Signal API 密钥：CO2 Signal 的密钥通过邮箱申请获得（在 CO2 Signal 官网 的输入框中填写你的邮箱即可申请）；
• 区域代码（zone code）：需要与 Electricity Map 上的区域相对应，可用 Electricity Map 的区域接口 api.electricitymap.org/v3/zones 查询你所在区域的代码。课程作者举例：在波士顿（Boston）使用的是 US-NEISO。

将 API 密钥和区域代码填入扩展界面后，扩展栏上的彩色圆点就会随该区域的能源使用强度变化而改变颜色，为你提供一个"现在适不适合做高耗能活动"的直观指示。

圆点颜色背后的实现：从源码看碳强度分级

起步代码 src/index.js 目前是带编号注释的空骨架（标注了表单字段、结果区、API 调用、localStorage 设置、表单提交处理、初始化检查、监听器与启动等占位注释），完整的参考实现在 solution/src/index.js。对照源码可以更清楚地理解文档中"圆点颜色变化"的机制：

颜色分级（co2Scale 与五档色值）。参考实现中定义了碳强度分档与对应颜色：

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

即碳强度（grams CO2/kWh）在 0 附近为绿色 #2AA364，随强度上升依次变为黄色 #F5EB4D、橙色 #9E4229，到 750/800 区间为深褐 #381D02。计算出的最近档颜色通过 chrome.runtime.sendMessage({ action: 'updateIcon', value: { color: closestColor } }) 发给后台，从而刷新扩展栏图标的颜色——这正是文档所说"点会变色"的底层调用链。

API 调用。参考实现通过 axios 请求 https://api.co2signal.com/v1/latest，参数为 countryCode: region，请求头携带 auth-token（即你申请的密钥）：

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

响应中会取 data.carbonIntensity（克 CO2 / 千瓦时）与 data.fossilFuelPercentage（化石燃料发电占比），并做了空值校验：任一字段缺失就抛出 Missing carbon intensity or fossil fuel data，在 UI 上提示"Sorry, data unavailable for the selected region."。

localStorage 与初始化。参考实现把 apiKey 与 region 存入 localStorage；扩展每次打开时 init() 会先检查这两个键——有则直接拉取数据、显示结果并显示清除按钮，没有则显示表单。清除按钮只移除 region 后重新初始化。这些细节对应起步骨架注释中标注的第 2、3、5 步（设置监听器与启动、初始检查、用户密钥/区域设置）。

小结与继续学习

按本文走完 npm install → npm run build → Edge "Load Unpacked" 加载 dist → 填入 API 密钥与区域代码，你就拥有了一个可用的 Carbon Trigger 起步扩展；对照 solution 补全 start 骨架 中的表单、API 调用与 localStorage 逻辑，则是把起步代码变成完整扩展的过程。本模块的三节配套课程可继续深入：浏览器工作原理、表单与 localStorage、后台任务与性能，模块总览见 5-browser-extension 的 README。