Chrome插件开发入门：手把手教你写第一个Hello World扩展

本节目标：亲手做出一个能加载、能点开的极简扩展，跑通”写代码→加载→看效果”的完整链路，并知道加载失败怎么查。

5-1 先确定目录和文件，再写清单

我们做一个最小的扩展：点工具栏图标，弹出一个写着”Hello Extensions”的小窗。它只需要三个文件。哪怕只有三行，能跑起来就是胜利。

hello-world/
├── manifest.json     # 清单，必需
├── hello.html        # 弹出页
└── hello.js          # 弹出页脚本

图标这一章先用可选的，后面再说怎么补。先把核心跑通，比什么都重要。

清单是一切的起点。最小可运行的 MV3 清单只要四个字段：manifest_version、name、version，再加一个 action 指向弹出页。

{
  "manifest_version": 3,
  "name": "Hello Extensions",
  "version": "1.0",
  "action": {
    "default_popup": "hello.html",
    "default_title": "点击打招呼"
  }
}

manifest_version 必须是 3，这是 MV3 的身份证。name 是扩展名字，version 是版本号，用”主.次.修订”格式。action.default_popup 告诉浏览器：点图标时弹出的页面是 hello.html。

Note

字段名都是小写、用下划线连接，比如 default_popup。写错一个字母清单就会报错，加载时红字提示，照着改即可。

补充两个小规则。name 是用户看到的名字，可以带中文和空格，长度别太长以免工具栏显示不全。version 用三段数字如 “1.0.0”，每次往商店更新都要比上一版大，浏览器靠它判断该不该提示用户升级。

5-2 写弹出页：hello.html 与 hello.js

弹出页就是一个普通 HTML 页面，只是它活在扩展小窗里。我们放一句问候，再引一个脚本。

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello Extensions</h1>
    <script src="hello.js"></script>
  </body>
</html>

注意 charset="UTF-8"，中文才能正常显示。脚本用 <script src> 外部引入，别写内联脚本——MV3 的安全策略默认禁止内联，写了会被拦。

Tip

弹出页默认很小，内容别堆太多。这个 h1 已经够看清效果。想加样式就再引一个 css，思路和普通网页一致。

脚本里我们可以打一行日志，验证弹出页确实加载了脚本。点开弹出页后，这条日志会出现在对应控制台。

console.log("Hello World 扩展的弹出页已加载");

虽然只有一行，但它证明了”扩展页面能跑自己的 JS”这件事。后面你会在弹出页里写按钮、调接口、读写存储，都是从这里长出来的。

弹出页有个特点：每次点开都是一次全新的加载，关掉就销毁。所以别指望在弹出页里存跨次的状态，要持久化就用 storage。这个行为初学容易误会，先有个印象。

5-3 关于图标

严格说，最小清单不写图标也能加载。但浏览器会用默认灰块代替，工具栏和商店都显丑。正式做扩展，建议补一份 icons 声明。

{
  "icons": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

把四个尺寸的 png 放进 icons/ 目录即可。第一版可以先不配，等跑通了再美化，不影响学习主线。

Note

图标尺寸用 16、32、48、128 这些标准值。浏览器按场景自动挑合适的那张，你不用手动切换。

5-4 用 Load Unpacked 跑起来

代码写好了，现在把它装进浏览器。步骤一步一步来：

打开 chrome://extensions，确认右上角”开发者模式”已开启。
点击页面左上角的”加载已解压的扩展程序”按钮。
在弹出的文件选择框里，选中你的 hello-world 文件夹（选文件夹本身，不是里面某个文件）。
确认后，扩展卡片出现在页面里，名字就是 Hello Extensions。

加载成功，工具栏也会出现扩展图标。如果没看到，点工具栏的拼图图标，把 Hello Extensions 固定到工具栏。

Tip

加载报错别慌。最常见是 manifest.json 格式错了，比如少了逗号、引号不配对。浏览器会给出行号，对着改完点刷新就行。

5-5 改完怎么刷新与加载失败排查

你改了 hello.html 或 hello.js，只需关掉再重新点开弹出页，新内容就生效，不用刷新扩展。但如果你改了 manifest.json 或后台脚本，就要回到 chrome://extensions，点该扩展卡片上的刷新图标。

改了什么	要不要刷新扩展
弹出页 html / js / css	不用，重开弹出页即可
清单 manifest.json	需要刷新
服务工作者 background.js	需要刷新

第一次加载最容易碰这几类问题，提前给你排雷。

一是清单不是合法 JSON。比如中文用了全角引号、最后一项多了逗号。用编辑器自带的 JSON 校验先过一遍最稳。二是路径写错，比如 default_popup 指向的 hello.html 实际拼错文件名，浏览器会报找不到资源。

三是文件夹选错层级。一定要选包含 manifest.json 的那一层，别选了上层或里层。四是开发者模式没开，那样根本看不到”加载已解压”的按钮。

Note

出错时，扩展卡片下方会有一行红色错误信息，通常带文件名和行号。那是你最好的线索，先读它，再动手。

5-6 跑通之后

看到弹出页跳出”Hello Extensions”，你就已经是一名扩展开发者了。别小看这一步，它验证了从写文件到加载上线的整条通路，后面所有复杂功能都是在这条通路上长出来的。

接下来我们会逐个拆开清单字段，让你从”能跑”走向”会写”，慢慢做出真正有用的扩展。

如果弹出页没出现，先确认图标确实固定到了工具栏，再检查有没有加载报错。初学者八成的卡点都在清单格式上，耐心读红色提示，问题往往一行就能解决。把这第一个扩展跑顺了，后面的路就通了。

第一个扩展：Hello World

5-1 先确定目录和文件，再写清单

5-2 写弹出页：hello.html 与 hello.js

5-3 关于图标

5-4 用 Load Unpacked 跑起来

5-5 改完怎么刷新与加载失败排查

5-6 跑通之后