开发环境准备：加载第一个未打包扩展（开发者模式全流程）

写扩展不需要编译器、不需要 SDK，甚至不需要新建 git 仓库——一个文件夹加几个文本文件就是完整的工程。但有几个环境细节一开始没弄对，后面会浪费你大量时间。这篇把从零到「扩展跑起来」的全流程走一遍。

需要准备什么

浏览器版本在地址栏输入 chrome://version 查看。编辑器没有强制，团队协作或工程化建议直接用支持 JSON 校验的那款——manifest.json 里多一个逗号浏览器都会拒绝加载，编辑器的语法检查能救命。用 HBuilderX 做日常前端开发的话，可以直接把扩展目录当普通前端工程管理，技巧可参考 HBuilderX 效率技巧。

开发者模式：三步加载

扩展的「开发态」靠 chrome://extensions 页面支撑，流程如下：

1. 地址栏输入 chrome://extensions 回车，进入扩展管理页；
2. 打开右上角的「开发者模式」开关；
3. 点击左上角「加载已解压的扩展程序」，选中你的工程文件夹。

成功后列表里会出现你的扩展卡片。此刻它已经完全可用：图标会出现在工具栏（可能被折叠进拼图菜单，可点图钉固定），所有声明的权限已生效。

用目录结构表示，一个最小工程长这样：

hello-ext/
├── manifest.json
├── background.js
└── icons/
    ├── icon-16.png
    ├── icon-48.png
    └── icon-128.png

其中 manifest.json 是唯一的必需文件，哪怕只有三行也能加载：

{
  "manifest_version": 3,
  "name": "Hello Ext",
  "version": "0.1"
}

改完代码怎么刷新

这是新手最常踩的坑：改了代码不等于生效了。扩展代码的刷新规则按上下文分三类：

养成肌肉记忆：改任何东西之前，先回到 chrome://extensions 点一下重新加载，再看页面效果。90% 的「我明明改了为什么没反应」都死在这一步。

调试入口在哪

每个上下文有独立的调试入口，找不到入口是第二个常见卡点：

• Service Worker：扩展卡片上点「Service Worker」链接，弹出专属 DevTools，console、断点、Network 一应俱全；
• Content script：在目标网页按 F12 打开 DevTools，切到 Sources 面板的 Content scripts 分组，或直接看 Console（注意页面自己的报错混在一起，需要过滤）；
• popup：右键工具栏图标选「检查弹出内容」，或先点开弹窗再按 F12。

调试的完整技巧（含常见报错对照表）在第五章的 《调试技巧》 一篇专门展开，这里先记住入口位置。

开发态的边界

未打包加载的扩展只在本机本 Profile 生效，每次启动浏览器会弹「关闭开发者模式扩展」的提示，这属于正常现象。它不能分发给其他人，想给别人用就得走打包或上架流程，那是第五章的话题。

另外提醒一句：开发者模式里只加载你完全了解来源的代码。官方文档对未打包扩展的定位写得很清楚——仅用于开发过程中加载受信任的代码，见 https://developer.chrome.com/docs/extensions/how-to/distribute 。

环境就绪后，下一篇我们就正式动手，写第一个 Manifest V3 扩展。它功能极小，但五脏俱全：manifest、后台、图标一个不少。

多 Profile 与干净环境

扩展开发经常需要「干净」的浏览器环境验证问题：你装的十几个老扩展可能与新扩展冲突，登录态会干扰页面表现。官方解法是 Chrome 的用户 Profile（右上角头像 → 添加）。给扩展开发单开一个 Profile，里面不装任何其他扩展、不登录任何账号，调试结果才可信。发布前验证也应在干净 Profile 里走一遍完整安装流程。

此外记住两个常用地址：chrome://extensions 是扩展管理主页；chrome://extensions/shortcuts 是快捷键管理页（第四章 commands 一节会用到）。把 chrome://extensions 固定成书签，开发期间它的打开频率仅次于编辑器。

用开发者模式常见的三种「假故障」

加载失败或行为异常时，先排除这三种与环境相关的假故障：

1. 扩展卡片变灰且提示出错：多半是 manifest JSON 语法问题，点「错误」按钮看具体原因——它会精确告诉你第几行出了什么问题，比想象中友好；
2. 图标不见了：Chrome 会把新装扩展折叠进拼图菜单，点拼图图标找到它，点图钉固定到工具栏；
3. 改动始终不生效：回到第二章讲过的刷新规则，按「改了什么」对号入座——manifest 改动必须重载扩展，content script 改动还要刷新目标页面。

第四种情况值得单独提：路径带中文或空格导致的诡异失败。Chrome 在 Windows 上对扩展目录路径里的非 ASCII 字符偶有兼容问题，症状是资源加载失败或打包异常。养成习惯：扩展工程一律放在纯英文、无空格的路径下，如 D:\dev\hello-ext。

版本与目标浏览器

写代码前确认两件事。第一，浏览器版本要够新：MV3 的关键 API 分版本陆续到位，比如 scripting 是 88+，tabGroups 是 89+，alarms 最小周期降到 30 秒是 120+。目标 API 的最低版本在官方 API 参考页的 Availability 一栏都标注着，用到新 API 时记得在 manifest 里配 minimum_chrome_version，防止旧版本浏览器装上后行为异常。第二，如果想兼顾 Edge，它在 edge://extensions 有几乎一样的开发者模式流程，MV3 代码通常无需改动即可加载，个别差异后面跨浏览器章节再谈。

团队协作的目录约定

如果扩展项目不止你一个人，一开始就定下目录约定能省很多摩擦：

project/
├── src/            # 源码：js、css、html
│   ├── background/
│   ├── content/
│   └── popup/
├── assets/         # 图标与静态资源
├── manifest.json   # 建议由构建工具生成或校验
└── dist/           # 构建产物（加载/打包都用它）

加载已解压扩展时指向 dist 而不是 src，这样构建流程怎么变都不影响浏览器里的配置。图标统一放 assets 并在 manifest 里引用相对路径。manifest.json 是协作冲突的高发文件，多人项目建议用脚本生成或至少约定「谁改权限谁提交说明」。

环境检查清单

加载第一个扩展前，逐项确认：浏览器版本 ≥ 88；开发者模式已开启；扩展目录路径纯英文无空格；manifest.json 通过编辑器的 JSON 校验。四项全绿，下一篇的 Hello Ext 会非常顺利。

调试入口与报错对照在第五章 《调试技巧》 篇有完整展开，这里先记住入口位置。官方对应文档：https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world

另外提醒：扩展目录下的文件结构本身就是工程规范，多文件项目的管理技巧见 HBuilderX 效率技巧，跨编辑器通用。

本章由 WorkBuddy 原创整理，API 行为依据 Chrome 扩展官方文档（Manifest V3）。