Web-Dev-For-Beginners 项目实战：用 CO2 Signal API 构建 Carbon Trigger 浏览器扩展

Web-Dev-For-Beginners 项目实战：用 CO2 Signal API 构建 Carbon Trigger 浏览器扩展

【免费下载链接】Web-Dev-For-Beginners24 Lessons, 12 Weeks, Get Started as a Web Developer项目地址: https://gitcode.com/GitHub_Trending/we/Web-Dev-For-Beginners

本篇技术指南以 Web-Dev-For-Beginners 仓库中 Carbon Trigger 浏览器扩展的启动代码说明（该文档的意大利语翻译版，对应英文原版 solution/README.md）为骨架展开：你将学会如何拉取 tmrow 的 CO2 Signal API 实时电力碳强度数据，用 webpack 构建一个可在 Microsoft Edge（基于 Chromium）中安装的浏览器扩展，并借助"彩色圆点"图标随时感知本地区电力使用的"重量级"。读完本文，你将掌握从npm install、npm run build到 Edge 开发者模式加载dist目录、配置 API Key 与区域代码的完整落地流程，并深入理解其背后的数据获取、本地存储与图标着色实现。

项目背景：在浏览器里装一个"电力碳强度仪表盘"

Carbon Trigger 是整个 5-browser-extension 课程模块的收官实战项目。它的设计目标非常具体：利用 tmrow 的 CO2 Signal API 监测电力使用情况，构建一个直接在浏览器中提醒你"所在地区当前电力负荷有多重"的扩展。当你临时使用这个扩展时，它会帮你根据实时信息对"现在是否适合做高耗能活动"做出判断——比如是否该现在洗衣服、跑重型计算任务，还是等电网更清洁时再做。

从仓库结构看，该项目以"脚手架"方式提供了两份代码：

• 启动版（starter）：位于5-browser-extension/start/，对应本文档所说的"Code zum Starten（启动代码）"，适合跟随课程逐步填充功能；
• 完成版（solution）：位于5-browser-extension/solution/，即完整可运行实现，核心逻辑集中在 solution/src/index.js。

两个版本的使用与安装方式完全一致，下文以 solution 目录为主线展开。

环境准备与构建

前置条件：npm

文档明确要求本机必须安装 npm 的engines字段可以看到更精确的版本约束：

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

即需要Node.js 18+、npm 9+。若版本低于此，npm install阶段可能不会报错，但建议满足该约束以保证 webpack 构建链路的兼容性。

安装依赖

把代码下载到本地文件夹后，在项目根目录（即solution/或start/）执行：

npm install

该命令会依据package-lock.json安装锁定版本的依赖。本项目依赖非常轻量：

"dependencies": { "axios": "^1.15.0" }, "devDependencies": { "webpack": "^5.105.4", "webpack-cli": "^5.1.4" }

• axios：唯一运行时依赖，用于向 CO2 Signal API 发起 HTTP GET 请求；
• webpack / webpack-cli：构建工具，把src/index.js及其模块依赖打包成浏览器扩展可加载的产物。

用 webpack 构建扩展

npm run build

该命令对应 package.json 中的"build": "webpack"，默认将src/index.js打包输出到dist/目录。开发调试阶段还可以用npm run watch（对应"watch": "webpack --watch"），让 webpack 监听文件变更自动增量重建，省去反复手动构建。

说明：dist/是构建产物目录，不随仓库提交；运行npm run build后才会生成，安装扩展时选择的正是这个目录。

在 Microsoft Edge 中安装扩展

文档给出了完整的 Edge 安装步骤（Edge 基于 Chromium，因此下述流程与 Chrome 几乎一致）：

1. 点击浏览器右上角的"三个点"菜单，找到"扩展"面板（Extensions）；
2. 若尚未开启，打开左下角的**"开发人员模式"（Developer mode）**开关；
3. 点击**"加载解压缩的扩展"（Load unpacked）**按钮；
4. 在弹出的文件选择对话框中打开dist文件夹，扩展即被加载；
5. 加载后，浏览器扩展工具栏上会出现 Carbon Trigger 的图标。

重新构建代码后（如修改了src/index.js并再次npm run build），需要回到扩展管理页点击该扩展的刷新/重新加载按钮，改动才会生效。

配置 API Key 与区域代码

扩展加载后还不能立即工作，你需要两样东西：

1. CO2 Signal API 密钥

前往 CO2 Signal 官网，在页面输入框中填入你的邮箱，即可通过邮件获取 API Key。

2. 区域代码（Region Code）

区域代码对应 Electricity Map 上的分区标识，可查阅 api.electricitymap.org/v3/zones 接口获取完整列表。文档给出的示例是波士顿使用US-NEISO（美国新英格兰独立系统运营商区域）。

提示：不同国家/地区的代码格式差异很大，务必按 Electricity Map 的实际分区填写，否则 API 会返回错误，扩展界面会显示 "Sorry, data unavailable for the selected region."。

把 API Key 和区域代码输入扩展界面的表单后，扩展会：

• 将两者保存到浏览器的localStorage（对应源码中的setUpUser与init逻辑，见 solution/src/index.js）；
• 向 CO2 Signal API 发起实时请求；
• 根据返回的碳强度数值，把扩展工具栏上的彩色圆点渲染为对应的颜色，直观反映本地区当前电力使用强度，并给出"现在是否适合执行高耗能活动"的参考。

彩色圆点背后的原理：数据 → 颜色映射

这个"圆点变色"系统是整个扩展的视觉核心。文档说明其设计概念源自加州碳排放领域的Energy Lollipop 扩展。在 solution/src/index.js 中，映射逻辑由calculateColor函数实现：

calculateColor = async (value) => { let co2Scale = [0, 150, 600, 750, 800]; let colors = ['#2AA364', '#F5EB4D', '#9E4229', '#381D02', '#381D02']; let closestNum = co2Scale.sort((a, b) => { return Math.abs(a - value) - Math.abs(b - value); })[0]; let num = (element) => element > closestNum; let scaleIndex = co2Scale.findIndex(num); let closestColor = colors[scaleIndex]; chrome.runtime.sendMessage({ action: 'updateIcon', value: { color: closestColor } }); };

其算法要点：

• 五档碳强度刻度（单位 gCO₂/kWh）：0、150、600、750、800；
• 五种对应颜色：#2AA364（绿，清洁）、#F5EB4D（黄，中等）、#9E4229（橙，偏高）、#381D02（深棕，很高）；
• 最近邻匹配：把实际碳强度值与刻度数组排序，找到距离最近的档位，再通过findIndex定位颜色下标；
• 消息传递：通过chrome.runtime.sendMessage({ action: 'updateIcon', ... })把颜色发给后台脚本，后台脚本再调用chrome.action.setIcon更新工具栏图标。

这一"内容脚本 → 后台脚本 → 浏览器图标"的消息链路，正是 3-background-tasks-and-performance 课程讲解的核心架构——由于 Edge 基于 Chromium，这里使用的chrome.runtime、chrome.action等 API 在 Edge 中同样可用。

数据获取：axios 调用 CO2 Signal API

在displayCarbonUsage函数中，扩展通过 axios 发起请求（见 solution/src/index.js）：

await axios .get('https://api.co2signal.com/v1/latest', { params: { countryCode: region }, headers: { 'auth-token': apiKey }, }) .then((response) => { const data = response?.data?.data; if (data?.carbonIntensity == null || data?.fossilFuelPercentage == null) { throw new Error('Missing carbon intensity or fossil fuel data'); } let CO2 = Math.floor(data.carbonIntensity); calculateColor(CO2); // ...更新界面元素 });

请求的三个关键要素：

响应数据处理：

• data.carbonIntensity：当前碳强度，取整后展示为 "X grams (grams C02 emitted per kilowatt hour)"，即每千瓦时发电排放的二氧化碳克数；
• data.fossilFuelPercentage：化石燃料发电占比，格式化为两位小数的百分比 "X.XX% (percentage of fossil fuels used to generate electricity)"；
• 对缺失字段做了显式校验（carbonIntensity或fossilFuelPercentage为null时抛错），并在catch中给出友好错误提示，避免界面崩溃。

localStorage：记住用户的配置

为了让用户不必每次打开都重新输入 API Key 和区域代码，扩展利用浏览器localStorage做持久化。相关的完整数据流（setUpUser/init/reset）同样集中在 solution/src/index.js：

• 保存：setUpUser中执行localStorage.setItem('apiKey', apiKey)与localStorage.setItem('region', region)；
• 恢复：init中通过localStorage.getItem('apiKey')/localStorage.getItem('region')检查是否已有存档。若两个值都非null，则跳过表单、直接用存档发起 API 请求并显示结果；否则显示设置表单；
• 重置：reset中执行localStorage.removeItem('region')清除区域，回到首次设置状态。

init在脚本末尾被直接调用（init()），并在加载时把图标设为默认绿色，使用户在数据到达前也能看到扩展处于可用状态。这套"首次使用显示表单、老用户直接加载结果"的状态机设计，在 2-forms-browsers-local-storage 课程中有详细讲解，你可以在浏览器开发者工具（F12）的Application → Local Storage面板中直观看到这两个键值。

注意：扩展拥有独立于普通网页的 localStorage 隔离空间，与站点数据互不干扰。需要提醒的是，把 API Key 明文存放在 localStorage 仅适用于教学场景——任何可执行脚本都能读到该值，生产级应用应改用服务端安全存储。

常见问题排查

延伸学习

• 完整可运行实现：5-browser-extension/solution/（含 src/index.js 与 package.json）；
• 启动版脚手架：5-browser-extension/start/；
• 表单、localStorage 与 API 集成详解：5-browser-extension/2-forms-browsers-local-storage/README.md；
• 后台任务、动态图标与性能优化：5-browser-extension/3-background-tasks-and-performance/README.md；
• 本指南对应的原版文档：5-browser-extension/solution/README.md 及 意大利语翻译版。

构建完成后，打开扩展，输入 API Key 与区域代码，工具栏的圆点便会随你所在电网的实时碳强度呈现绿、黄、橙、深棕等颜色——现在你可以在浏览器里直观判断"此刻是否适合进行高耗能活动"了。

【免费下载链接】Web-Dev-For-Beginners24 Lessons, 12 Weeks, Get Started as a Web Developer项目地址: https://gitcode.com/GitHub_Trending/we/Web-Dev-For-Beginners