Web-Dev-For-Beginners：Carbon Trigger 浏览器扩展完整方案——用 CO2 Signal API 在浏览器里显示你所在地区的电网碳强度

本篇指南基于课程第 5 模块"Browser Extension"的成品代码说明文档（马来语版 README，位于 solution/translation/README.ms.md），完整讲解 Carbon Trigger 浏览器扩展的用途、构建与安装流程：你将学习如何用 npm 和 webpack 打包一个浏览器扩展，通过 Edge 的"Load Unpacked"机制加载未打包扩展，并配置 CO2 Signal API 密钥与电力区域代码，使扩展工具栏上的彩色圆点实时反映你所在地区的电力碳强度。读完本文，你能独立完成扩展的安装、配置与基本运行，并理解其源码中颜色分级、数据请求与本地持久化的实现逻辑。

这个扩展做什么

Carbon Trigger（碳触发器）是一个浏览器扩展：它调用 CO2 Signal 提供的 API，查询你所在电力区域当前的用电情况与碳强度（carbon intensity，即每消耗一千瓦时电力排放的二氧化碳克数），并在浏览器工具栏上用一个彩色圆点直观提示当前电网的"绿色程度"。

文档中说明的使用场景是：当你需要做一些耗电较高的活动（原文举例：烘干机等高碳强度活动）时，先看一下工具栏上的圆点，判断此时进行这类活动是否合适——圆点颜色越偏"绿"，说明当前电网清洁电力占比越高，此时进行高耗电活动的环境代价越小；反之则建议推迟。文档也指出，这个"圆点"图标的设计概念来自加利福尼亚排放提示类扩展 Energy Lollipop 的图标结构。

从 课程模块总览 可以看到，该模块定位是：构建一个可在 Edge、Chrome 和 Firefox 中运行的扩展，它会检查指定区域的电力使用与碳强度，并返回该区域的碳足迹读数；用户在表单中一次性输入 API 密钥和区域代码后，即可随时按需（ad hoc）查询。

环境准备与构建步骤

原始文档"Getting Started / Bermula Dari Sini"一节给出的操作前提与命令如下，本文在保留原文全部步骤的基础上，结合仓库中的 package.json 补充了版本约束与脚本细节。

前提条件

• 安装 npm。对照 solution 的 package.json，该项目声明了引擎要求：npm >= 9.0.0、node >= 18.0.0。如果你的 Node 版本低于 18，构建环境可能不满足要求，建议先升级 Node 再执行后续命令。
• 将这份代码（solution 目录）下载到本地计算机的一个文件夹中。

安装依赖并构建

# 安装所有必需的 npm 包
npm install

# 用 webpack 构建扩展，产物输出到 dist 文件夹
npm run build

结合 package.json 可以确认这两条命令背后的实际配置：

配置项	值	说明
scripts.build	webpack	执行一次完整构建，即 npm run build 实际调用的命令
scripts.watch	webpack --watch	监听模式构建，适合开发时边改边重新打包
构建依赖	webpack ^5.105.4、webpack-cli ^5.1.4	devDependencies，仅构建期需要
运行时依赖	axios ^1.15.0	扩展源码中用于请求 CO2 Signal API 的 HTTP 库

也就是说，npm run build 等价于直接运行 webpack；开发调试阶段也可以用 npm run watch 保持进程常驻、自动重新打包。构建完成后，扩展的打包产物位于 dist 文件夹，这是下一步安装时的关键路径。

在 Edge 中加载未打包扩展

原文档给出的 Edge 安装步骤是：

1. 点击浏览器右上角的"三个点"菜单，找到 Extensions（扩展）面板；
2. 在扩展面板中选择 "Load Unpacked"（加载未打包扩展） 来加载一个新扩展；
3. 在弹出的目录选择窗口中打开 dist 文件夹，扩展即完成加载。

这一步体现的是 Chrome 系浏览器的"未打包扩展"安装机制：浏览器不要求你提供 .crx 等打包格式，而是直接指向构建产物目录（本例中即 dist）来加载。加载成功后，你可以在工具栏看到这个扩展的图标——按文档描述，它会显示为一个带颜色的圆点。

配置 API 密钥与区域代码

扩展加载后并不能直接工作。原文档指出，要真正使用它，你还需要两样东西：

• CO2 Signal API 的密钥：通过邮件在 CO2 Signal 官网注册获取（在页面上的邮箱输入框中填入你的邮箱即可申请）；
• 你的电力区域代码：对应 Electricity Map 上的区域划分，例如文档作者所在的波士顿使用的区域代码是 US-NEISO。

将这两项填入扩展的表单界面后，扩展会立即发起一次查询，工具栏上的彩色圆点就会改变颜色，以反映你所在区域当前的能源使用情况，为你判断"哪些高耗能活动现在适合做"提供依据。

源码解析：圆点颜色是怎么算出来的

以下实现细节来自 solution/src/index.js，与文档中"圆点会随区域能耗变化颜色"的描述一一对应。

颜色分级逻辑（index.js 第 17–32 行）

扩展内置了一个碳强度刻度表和与之对应的颜色数组：

刻度值（g CO2/kWh 附近）	0	150	600	750	800
对应颜色	#2AA364（绿）	#F5EB4D（黄）	#9E4229（褐红）	#381D02（深褐）	#381D02（深褐）

calculateColor 函数拿到碳强度数值后，先在刻度表中找出与该值最接近的刻度，再确定其后的颜色档位，最后通过 chrome.runtime.sendMessage({ action: 'updateIcon', value: { color: closestColor } }) 把颜色发送给扩展的其他部分，从而更新工具栏图标的颜色。从源码结构看，这意味着"圆点颜色"并非由页面 CSS 直接控制，而是通过 Chrome 扩展的消息机制（runtime message）传递给负责图标渲染的部分，这是浏览器扩展中内容页面与后台协作的常见模式。

数据请求与校验（index.js 第 34–68 行）

displayCarbonUsage 函数用 axios 请求 CO2 Signal 的 https://api.co2signal.com/v1/latest 接口，参数为区域代码（countryCode），请求头中携带 auth-token 即你申请的 API 密钥。拿到响应后会做两件事：

• 校验返回数据中 carbonIntensity 与 fossilFuelPercentage 是否缺失，缺失则抛出错误；
• 展示结果：碳强度取整后显示为"grams (grams CO2 emitted per kilowatt hour)"，化石燃料占比保留两位小数显示为百分比；若请求失败，则在界面上提示"Sorry, data unavailable for the selected region."，而不是让页面直接崩溃。

本地持久化（index.js 第 71–123 行）

• 表单提交时，setUpUser 会把 API 密钥和区域分别写入 localStorage（键名 apiKey、region），然后立即发起首次查询；
• 扩展启动时的 init 函数会先检查 localStorage 中是否已有这两个值：若没有，显示表单等待用户输入；若有，则自动用已保存的配置重新拉取数据，无需再次填写；
• 界面上的清除按钮（reset）只会移除 region 记录并重新初始化，让用户可以切换到其他区域。

这段实现正好对应本模块第 2 课"表单与 localStorage"的教学目标：浏览器扩展本质上也是一个"迷你网站"，同样依赖表单、本地存储和 API 调用这套前端技术栈。

延伸：与本模块其他课程的关系

本成品方案是 Browser Extension 模块 三节课的集大成结果，各课主题文档可继续深入：

• 关于浏览器的工作原理：理解扩展为何能在浏览器中运行；
• 表单、浏览器与本地存储：对应源码中表单提交与 localStorage 持久化的部分；
• 后台任务与性能：对应扩展的后台脚本与图标更新机制，以及性能测量方法。

此外，仓库中 start/README.md 是配套的"起步代码"说明文档，与本 solution 文档内容结构一致，适合在动手练习前对照阅读；其他语言的 solution 译本（西班牙语、法语、印地语、意大利语、日语等）位于 solution/translation 目录。

适用前提与限制：本文所有步骤均基于当前仓库 solution/package.json 声明的构建方式（webpack 5 打包至 dist 目录）与 solution/src/index.js 的实现；运行扩展必须自行申请 CO2 Signal API 密钥，且查询结果是否可用取决于你所在区域是否被 CO2 Signal 覆盖——源码中对数据缺失的情况已有明确的界面提示。