第一个 Chrome 插件：15 分钟跑通 Hello World

💡 一句话总结：一个文件夹、三份文件、Chrome 开发者模式——15 分钟，让浏览器弹出你自己插件的 Hello World。

上一课 C1 浏览器插件是什么把概念讲完了：插件就是 HTML/CSS/JS 加一份 manifest.json。这一课动手——chrome 插件入门最扎实的一步，不是再背十个名词，而是让浏览器真的弹出你自己的插件。

别跳过这 15 分钟——哪怕你打算全程让 AI 写代码。本地加载、刷新、看弹窗这三个动作永远得你自己按，Hello World 就是把它们练成肌肉记忆。

学完你能做什么

• 做出一个真的装进 Chrome 的插件：点工具栏图标，弹出「Hello Extensions」
• 逐字写出 manifest.json 官方最小示例，说出每个字段干什么
• 用 chrome://extensions → 开发者模式 → Load unpacked 三步完成本地加载
• 把插件 Pin 到工具栏，随点随用
• 记住重载规则：改哪些文件要刷新插件、改哪些不用

你现在的困境

• 「插件名词背了一堆：manifest、MV3、popup……但一行代码都没在浏览器里跑起来过」
• 「AI 把代码写好了，可这些文件放哪、Chrome 怎么才能认出它们，我不知道」
• 「照网上老教程抄，Load unpacked 一点就报错，也不知道错在哪」

什么时候用这一招

当你需要：

• 把「做一个插件」从念头变成现实——先跑通最小的，再往上加功能
• 验证开发链路没问题：能建文件、能加载、能看到弹窗，三关全过
• 给 AI 的需求一个落地起点：先 Hello World 跑通，下一课再让 AI 往上盖楼

而且不想：

• 一上来啃 manifest 全部字段——下一课 C3 再逐个拆
• 碰打包、上架、审核——那是 C6 的事
• 装任何开发环境——一个文件夹 + Chrome 自带的开发者模式就够

🎒 开始前的准备

• 走完 C1 浏览器插件是什么，知道插件 = HTML/CSS/JS + manifest.json，现在只写 MV3
• 电脑上装着 Chrome 浏览器
• 一个能新建、编辑文本文件的工具（系统记事本就行；VS Code 这类代码编辑器更舒服）
• 15 分钟

核心思路

一个 Chrome 插件的最小形态，就是一个文件夹加三份文件：

文件	作用	谁用它
manifest.json	插件的身份证 + 说明书：叫什么、版本多少、点图标干什么	Chrome 读它
hello.html	点工具栏图标弹出的那个小页面	用户看它
hello_extensions.png	工具栏图标（可以省掉，Chrome 会给通用图标）	用户看它

运行原理一句话：Chrome 靠 manifest.json 认识你的插件；manifest 里 action.default_popup 告诉 Chrome「点工具栏图标时，打开 hello.html」。

动手前先立两条规矩：

1. manifest_version 只写 3。官方明说唯一支持的值就是 3；老教程里的 2 别抄（C1 讲过 MV2 已被全面禁用，字段规则 C3 详解）。
2. 开发者模式 ≠ 上架。开发者模式 + Load unpacked 只是「允许把本地文件夹装进浏览器」的开关；上架 Chrome 应用商店要走开发者注册和审核，是另一条路（见 C6）。

💡 这一课要手敲吗

三份文件少到手敲只要几分钟，建议第一次自己敲——这一步最容易死在一个引号、一个字段名上，手敲一遍，以后才知道该核对 AI 写的哪里。从下一课开始文件越来越多，那才是 AI 的主场。

跟我做

第 1 步：创建插件文件夹

为什么：插件就是「一个文件夹里的几份文件」，先给它们安个家。

操作：在桌面（或任何你找得到的地方）新建一个文件夹，起名 hello-extensions。

想对照成品的话，官方示例源码在 GitHub：GoogleChrome/chrome-extensions-samples 仓库的 functional-samples/tutorial.hello-world 目录。但这一课建议自己建——总共就三份文件。

你应该看到：一个空文件夹。

第 2 步：写 manifest.json——chrome 插件入门的第一个文件

为什么：Chrome 只认 manifest.json。没有它，这个文件夹就只是个普通文件夹。

操作：在文件夹里新建 manifest.json，内容逐字照抄官方示例：

{
  "name": "Hello Extensions",
  "description": "Base Level Extension",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  }
}

六个字段各干什么：

字段	本课的值	干什么
name	Hello Extensions	插件名，显示在扩展页等地方
description	Base Level Extension	一句话描述
version	1.0	版本号（1-4 段以点分隔的整数）
manifest_version	3	声明用 MV3——唯一支持的值
action.default_popup	hello.html	点工具栏图标弹出这个页面
action.default_icon	hello_extensions.png	工具栏图标用这张图

⚠️ 两个细节

• JSON 里不能写注释——// 和 /* */ 都会让解析直接失败。想记笔记，写在文件外面。
• 不想准备图标？把 "default_icon" 那一行整个删掉，Chrome 会自动给插件一个通用图标。

你应该看到：文件夹里躺着一个 manifest.json。

• 小检查：用编辑器重新打开它，确认 "manifest_version": 3，每个引号都成对

第 3 步：写 hello.html，配一张图标

为什么：default_popup 指向的文件必须真实存在，点图标才有东西可弹。

操作：新建 hello.html，内容照抄官方示例：

<html>
  <body>
    <h1>Hello Extensions</h1>
  </body>
</html>

图标二选一：

• 方式 A（照官方示例）：从官方教程页下载示例图标，改名为 hello_extensions.png 放进文件夹——文件名必须和 default_icon 写的一字不差。
• 方式 B（更省事）：上一步已删掉 default_icon 的话，直接跳过，Chrome 会给通用图标。

你应该看到：文件夹里两三个文件：manifest.json、hello.html，加上图标（如果选了方式 A）。

第 4 步：打开 chrome 开发者模式，Load unpacked 本地加载

为什么：Chrome 默认只装商店里的插件。开发者模式是「允许本地安装」的开关，Load unpacked 负责把你的文件夹装进浏览器。

操作（官方三步）：

1. 新标签页地址栏输入 chrome://extensions 回车，打开扩展管理页。另外两个入口：工具栏拼图按钮 → Manage Extensions；或 Chrome 菜单 → More Tools → Extensions。
2. 打开 Developer mode（开发者模式）开关。
3. 点 Load unpacked，在文件选择框里选中你的插件文件夹。

注意：选的文件夹里必须直接躺着 manifest.json——官方要求它放在插件根目录，多套一层子文件夹 Chrome 就找不到了。

你应该看到：扩展页列表里出现 Hello Extensions，提示 The extension has been successfully installed.（插件已成功安装）；没给图标的话，Chrome 自动配了一个通用图标。

• 小检查：Hello Extensions 卡片正常显示，没有弹出错误对话框

第 5 步：Pin 到工具栏，点开你的第一个弹窗

为什么：本地加载的插件默认藏在拼图菜单里，每次都要多点一下；Pin 出来才顺手。

操作：点工具栏的拼图按钮，找到 Hello Extensions，点它旁边的图钉图标（Pin）固定到工具栏。然后点工具栏上这个插件的图标。

你应该看到：一个小弹窗弹出来，写着 Hello Extensions——你的第一个 Chrome 插件跑通了。

第 6 步：改代码，学会刷新插件

为什么：插件不会自动读取你改过的文件，大部分改动必须手动刷新才生效——这是新手最容易误判成「AI 写错了」的地方。

操作：把 manifest.json 里的 name 改成 "Hello Extensions of the world!"，保存。回到 chrome://extensions，点插件卡片上 on/off 开关旁边的刷新图标。

你应该看到：插件名字变成 Hello Extensions of the world!。不点刷新，它就还是旧名字。

官方的重载规则表，现在就记住：

改了什么	要刷新插件吗
manifest	要
Service worker	要
Content scripts	要（还要刷新所在网页）
弹窗（popup）	不用
设置页（Options page）	不用
其他插件 HTML 页面	不用

本课的插件只有 manifest 和 popup 两类文件，口诀很简单：改 manifest，去扩展页点刷新；改 hello.html，不用刷新——重新点开弹窗，看到的就是新内容。

检查点 ✅

• chrome://extensions 里 Hello Extensions 卡片正常显示，没有报错
• 插件已 Pin 到工具栏，点图标能弹出 Hello Extensions
• 改过 name 后，去扩展页点了刷新图标，名字变了
• 能说出重载规则：manifest、service worker、content scripts 要刷新；popup 和其他 HTML 不用
• 知道开发者模式只是「本地加载」的开关，上架要走注册 + 审核（C6）

踩坑提醒

❌ 在 manifest.json 里写注释

JSON 不支持注释。写了 // 或 /* */，manifest 就解析失败——本地加载时直接弹错误对话框；官方也明说打包上传时 JSON 里有注释会报 Cannot parse the manifest。

正确做法：注释和笔记写在文件外面；字段含义拿不准，查 C3 字段速查。

❌ 照抄老教程，manifest_version 写成 2

网上大量教程写于 MV2 时代。现在 manifest_version 唯一支持的值是 3，MV2 插件也已被 Chrome 全面禁用——照抄等于白干。

正确做法：开工前先看一眼这一行是不是 "manifest_version": 3；看到教 MV2 的教程直接关掉。

❌ 改了代码不刷新插件，以为「AI 写错了」

改 manifest、service worker、content scripts 后不刷新，浏览器里跑的还是旧代码——你会误以为代码有问题，让 AI 反复改一段完全正确的代码。

正确做法：改完先按第 6 步的重载规则表过一遍：该刷新的去扩展页点刷新图标，改 popup 则不用。还不对，再去 C5 找日志。

❌ 以为打开开发者模式就算「上架了」

开发者模式只是允许本地安装的开关，此时的插件只有你自己能用。上架 Chrome 应用商店必须走开发者注册（交一次性注册费，金额以开发者后台实付页为准）和审核。

正确做法：本地跑通后，按 C6 上架全流程走注册、打包、提审。

进阶技巧（可选）

🚀 给弹窗加一行日志，提前认识调试。给 hello.html 的 </body> 前加一行 <script src="popup.js"></script>，新建 popup.js 写 console.log("This is a popup!")。打开弹窗 → 右键弹窗 → Inspect → Console 面板，就能看到这条日志。故意写错代码（比如少个引号）时，扩展页会出现 Errors 按钮，点开看详情。service worker、content script 的日志在哪，C5 有完整地图。

项目结构随你：官方明说组织方式自由，唯一硬要求是 manifest.json 放在插件根目录。用 TypeScript 的话，装 npm 包 chrome-types 可以获得 Chrome API 自动补全——它随 Chromium 源码自动更新，官方提醒要经常升级。

本课小结

✅ chrome 插件入门第一课，你已经：

• 做出并跑通了第一个插件：文件夹 + manifest.json + hello.html，点图标弹 Hello Extensions
• 掌握本地加载三步：chrome://extensions → Developer mode → Load unpacked
• 会把插件 Pin 到工具栏随点随用
• 记住重载规则：manifest、service worker、content scripts 改完要刷新，popup 不用
• 知道日志第一入口：弹窗右键 Inspect

关键配置字段回顾：

字段	本课的值	说明
manifest_version	3	唯一支持的值，别写 2
name	Hello Extensions	插件名
description	Base Level Extension	描述
version	1.0	版本号，1-4 段点分整数
action.default_popup	hello.html	点图标弹出的页面
action.default_icon	hello_extensions.png	图标；不写则用通用图标

下一课预告

下一课 C3 manifest.json 详解：把这份最小说明书逐字段拆开。你会学到：

• 三个必填字段的规则：name 最长 75 字符、version 的格式细节
• 上架必补的字段：description（最长 132 字符）、icons
• content_scripts、permissions 这些高频可选字段怎么写
• 为什么上传商店后改一个错字，都得提高版本号重新打包

准备好了就进 C3 →