夜雨聆风
AI开发系列:开发一个功能完整的浏览器插件(第1篇)
你有没有这样的经历，你在研究某个技术问题，开了20多个标签页，每个都觉得有用。不断切换跳转，突然浏览器崩溃了，标签页全没了。你盯着空荡荡的浏览器窗口，心里一万头草泥马奔腾而过。或者网上学习时，看到一篇关于 React 新特性的好文章，随手截了个图，心想”明天再仔细看”。过两天遇到一个问题，打开电脑，想找那篇文章——翻遍了微信传输助手、浏览器书签、桌面截图文件夹，就是找不到。最后只能凭着模糊的记忆继续胡乱搜索，结果搜出来一堆文章，哪篇是你看过的？不知道。
说了这么多，现在要开始装逼了。这就是我随手开发「时间轴随手记」的初衷，一直有这个想法，奈何能力时间有限。现在有了ai咔咔咔一顿输出，就诞生了我人生中第二个插件！作为一个重度信息收集者（说白了就是收藏不看），我深知碎片化信息管理的痛苦。市面上的方案要么太重（Notion、Obsidian），要么功能单一（单纯的书签管理器），要么需要联网同步（我不想把所有数据传到云端）。
在一个艳阳高照的下午我突然想：为什么不做一个浏览器插件呢？（AI来做）
- 随手记录：看到什么直接截图或记笔记，不用切换应用(随时访问来源)
- 智能回顾：再次访问相关网页时，自动提醒你之前的记录。
- 网页批注：随时批注重要内容。
- 关联图谱：可视化你的知识网络，发现意想不到的联系。
说干AI就干。今天就介绍这个项目从0到1的开发历程，以及浏览器插件开发的那些事儿。（不足之处海涵）
想先体验一下成品？ – 🔗 Edge 插件市场：（为什么没chrome，问就是穷。注册要5美元，关键要国外信用卡啊）
https://microsoftedge.microsoft.com/addons/detail/kbkmnnpkgcjkgoolgklolpeabndocnfd二、项目介绍：时间轴随手记
2.1 这是个什么项目？
「时间轴随手记」（Timeline Quick Notes）是一个浏览器扩展，核心功能很简单：
- 📸 智能截图：全屏或区域截图，支持画笔、箭头、文字、马赛克等编辑工具，一条记录最多支持10张图片
- 📝 快速笔记：随时记录想法，支持 Markdown 和代码语法高亮
- 📋 网页剪藏：保存选中内容或整页，离线也能查看
- ⏰ 时间轴展示：按时间线组织所有记录，支持列表、网格、日历、图谱等多种视图
- 🔍 智能回顾：再次访问相关网页时，自动提醒你之前的记录（支持 URL 精确匹配和域名匹配）
- 🕸️ 关联图谱：基于标签、域名、手动关联自动计算关联强度，用 Cytoscape.js 可视化你的知识网络
- ✏️ 沉浸式批注：在网页上直接批注，XPath 精准定位，下次访问自动高亮
- 🎨 分享卡片：9种精美样式，支持二维码，一键生成高清分享图
- 🐱 宠物助手：页面悬浮的可爱宠物（10种形象可选），环形菜单快捷入口，还会自己溜达（这是为了圈钱想的功能）
2.3 系列文章规划
这个项目涉及的技术点太多了，一篇文章肯定讲不完。所以我打算写一个系列，分以下几篇来讲（想到哪写到哪）：
- 第一篇（本篇）：项目起源、技术选型、整体架构
- 第二篇：核心功能实现（上）- 截图、存储、消息传递
- 第三篇：核心功能实现（下）- 智能回顾、关联图谱
- 第四篇：差异化功能 – 可爱的宠物助手（动画系统、自主行为、性能优化）
- 第五篇：测试驱动开发 – 单元测试、属性测试
- 第六篇：踩坑与爬坑 – 数据迁移、跨浏览器兼容、内存管理
每篇文章都会有真实的代码示例、架构图、流程图，以及我踩过的坑。希望能帮自己少走弯路。
三、技术选型：选择比努力更重要
技术选型这事儿，说实话挺纠结的。选对了事半功倍，选错了就是给自己挖坑。我在项目初期花了整整一会会做调研和对比，最后确定了这套技术栈。（AI推荐）
3.1 原生 JavaScript vs 框架（React/Vue）
这是第一个要做的决定。很多人可能会说：“都2030年了，还用原生 JS？”我的考虑是这样的：(后面两个不会)
为什么不用框架？（下面凑字数，纯属自己不会框架，怕AI搞出来看不懂）
- 包体积：React + ReactDOM 压缩后也要 130KB+，Vue 3 也要 80KB+。对于浏览器插件来说，这个体积不算小。用户每次打开 Popup 都要加载这些代码。
- 性能开销：虚拟 DOM、响应式系统都有运行时开销。对于插件这种需要快速响应的场景，原生 JS 的性能更好。
- 学习曲线：只需要会 JavaScript 就行，不需要学 React Hooks 或 Vue Composition API。
- 构建复杂度：不用框架意味着不需要复杂的构建配置，一个简单的脚本就能搞定。（纯找借口….）
原生 JS 的优势：
-
零依赖，包体积小（整个插件压缩后不到 1024KB,那是不可能的快3M多了） -
性能好，启动快 -
代码直观，容易理解 -
调试方便，不需要 Source Map
当然也有劣势：
-
没有组件化，代码复用需要自己封装 -
没有响应式，状态管理需要手动处理 -
DOM 操作比较繁琐
综上所述。对于这个项目来说，因为我不会框架所以我使用原生JS。
3.2 Manifest V3：拥抱新标准
Chrome 从 2023 年开始强制新插件使用 Manifest V3（MV3），V2 已经不再支持了。虽然 MV3 有些限制（比如不能用 eval()，Background Page 变成了 Service Worker），但它带来的好处也很明显：
MV3 的优势：
- 更好的性能：Service Worker 按需启动，不会一直占用内存
- 更强的安全性：更严格的 CSP 策略，减少 XSS 风险
- 未来趋势：所有浏览器都在往这个方向走
MV3 的挑战：
- Service Worker 限制：不能直接操作 DOM，不能使用 window 对象
- 生命周期管理：Service Worker 会被浏览器随时终止，需要处理好状态恢复
- 调试困难：Service Worker 的调试比 Background Page 麻烦一些
不过这些挑战都是可以克服的。而且拥抱新标准总是对的，反正不是我干活。
3.3 IndexedDB vs Chrome Storage
数据存储方案的选择也很关键。Chrome 提供了两种主要的存储方式：
|
特性 |
Chrome Storage |
IndexedDB |
|
存储容量 |
5MB（sync）/ 10MB（local） |
无限制（受磁盘空间限制） |
|
数据结构 |
简单的 Key-Value |
支持复杂对象、索引、事务 |
|
查询能力 |
只能按 Key 查询 |
支持索引查询、范围查询 |
|
性能 |
读写快，但容量小 |
容量大，查询灵活 |
|
API 复杂度 |
简单（Promise-based） |
复杂（基于事件的回调） |
|
适用场景 |
配置、设置 |
大量数据、复杂查询 |
对于这个项目，我需要存储大量的截图、笔记、网页内容，Chrome Storage 的容量明显不够。而且我需要按时间、标签、域名等多个维度查询数据，IndexedDB 的索引功能正好满足需求。
最终方案： – IndexedDB：存储记录、标签、批注、关联等核心数据 – Chrome Storage：存储用户设置、高级功能配置。这样既能利用 IndexedDB 的大容量和查询能力，又能用 Chrome Storage 快速读取配置。
3.4 Cloudflare 技术栈：Workers + Pages
项目后期我加入了想想能不能圈点钱加入了高级功能，需要实现许可证验证。传统方案是搭建一个后端服务器，但我不想维护服务器（穷），也不想付高昂的服务器费用。
Cloudflare Workers 完美解决了这个问题（免费）：
- 无服务器：不需要管理服务器，代码部署到全球边缘节点。
- 按需计费：免费额度每天 10 万次请求，对于个人项目完全够用
- 全球 CDN：自动在全球 200+ 个城市部署，访问速度快（这个刷刷能用）
- 简单易用：用 JavaScript 写 API，和前端代码无缝衔接
同时，项目官网使用 Cloudflare Pages （官网也可以白嫖了）部署：
- 免费托管：静态网站免费托管，无限流量
- 自动构建：Git 推送后自动构建部署
这套组合拳下来，我的后端成本几乎为零，而且性能还中。强烈推荐给个人开发者。给Cloudflare跪一个不亏是活菩萨（YYDS）。
3.5 技术栈总览
最终确定的技术栈：
前端运行时：原生 JavaScript (ES Module)、HTML、CSS 数据存储：IndexedDB + Chrome Storage 图谱可视化：Cytoscape.js 测试框架：Jest + fast-check 构建工具：Node.js 自定义脚本 云服务：Cloudflare Workers + Pages 插件标准：Manifest V3
这套技术栈用下来，我觉得还是挺满意的。性能好、成本低、维护简单（简单不麻烦是真的）。
四、架构设计：搭建稳固的地基
技术选型确定后,就该设计架构了。浏览器插件的架构和普通网页应用不太一样，需要理解它的运行机制。
4.1 浏览器插件的基本概念
让开我要开始装逼了，虽然我也是边做边学。如果你之前没开发过浏览器插件，可能会对这些概念有点懵。我用最简单的方式解释一下：
Background Service Worker（后台服务） – 插件的”大脑”，负责处理核心逻辑 – 在后台运行，不依赖任何页面 – 可以监听浏览器事件（标签页切换、右键菜单点击等） – MV3 中是 Service Worker，会被浏览器按需启动和终止。
Content Script（内容脚本） – 注入到网页中运行的脚本 – 可以访问和修改网页 DOM – 可以和 Background 通信 – 每个标签页都有独立的 Content Script 实例
Popup（弹出窗口） – 点击插件图标时弹出的小窗口 – 是一个独立的 HTML 页面 – 可以和 Background 通信 – 关闭后会被销毁，不保留状态
Options（设置页面） – 插件的设置页面 – 也是一个独立的 HTML 页面 – 通常用来配置插件的各种选项
独立页面（如 Timeline） – 完整的浏览器标签页 – 可以展示复杂的 UI – 适合需要大量空间的功能
4.2 整体架构图
来看看「时间轴随手记」的整体架构：
4.3 模块划分与职责
我把代码分成了几个清晰的层次：
1. 用户界面层 – popup: 快速操作入口（截图、笔记、剪藏） – timeline: 时间轴展示（列表、网格、日历、图谱视图） – options/: 设置页面（主题、快捷键、高级功能）
2. 内容脚本层 – content/content.js: 主入口，协调各个功能 – content/region-selector.js: 区域选择器
– content/recall-bubble.js: 智能回顾气泡 – content/immersive-sidebar.js: 沉浸式批注侧边栏
– content/pet-assistant/: 宠物助手（差异化功能，包含10个子模块）
3. 后台服务层 – background/background.js: 消息路由、事件监听、API 调用
4. 服务层（28个组件 + 20个服务模块） – services/storage.js: IndexedDB 封装
– services/screenshot.js: 截图处理
– services/export.js: 多格式导出
– services/search.js: 搜索引擎
– services/recall.js: 智能回顾逻辑
– services/relation.js: 关联计算
– services/premium.js: 高级功能管理 – … 还有很多
5. 组件层 – components/: 可复用的 UI 组件（28个） – 比如：timeline.js、record-card.js、graph-view.js、markdown-editor.js 等
4.4 数据流设计
来看一个典型的数据流：用户截图并保存
这个流程展示了各个模块之间的协作： 1. Content Script 负责 UI 交互。 2. Background 负责调用浏览器 API 。3. Storage Service 负责数据持久化 4. 消息传递串联整个流程。
4.5 目录结构
最后看看项目的目录结构：
timeline-notes/├── background/ # 后台服务 (1个文件)│ └── background.js├── components/ # UI组件 (28个文件)│ ├── timeline.js│ ├── record-card.js│ ├── graph-view.js│ ├── markdown-editor.js│ └── ...├── content/ # 内容脚本 (14个文件)│ ├── content.js│ ├── region-selector.js│ ├── recall-bubble.js│ ├── immersive-sidebar.js│ └── pet-assistant/ # 宠物助手 (10个文件)│ ├── pet-assistant.js│ ├── animation-controller.js│ ├── wander-controller.js│ ├── mood-manager.js│ └── ...├── services/ # 服务层 (20个文件)│ ├── storage.js│ ├── screenshot.js│ ├── export.js│ ├── search.js│ ├── recall.js│ ├── relation.js│ └── ...├── popup/ # 弹出窗口 (3个文件)│ ├── popup.html│ ├── popup.js│ └── popup.css├── timeline/ # 时间轴页面 (3个文件)│ ├── timeline.html│ ├── timeline.js│ └── timeline.css├── options/ # 设置页面 (3个文件)│ ├── options.html│ ├── options.js│ └── options.css├── locales/ # 国际化 (4个文件)│ ├── en.json│ ├── zh-CN.json│ ├── zh-TW.json│ └── ja.json├── styles/ # 样式文件 (7个文件)│ ├── common.css│ ├── themes.css│ └── ...├── tests/ # 测试文件 (29个文件)│ ├── storage.test.js│ ├── recall.property.test.js│ └── ...├── libs/ # 第三方库│ ├── cytoscape.min.js│ └── ...├── website/ # 官网 (Cloudflare Pages)├── worker/ # Cloudflare Workers└── manifest.json # 插件配置文件
这个结构清晰地分离了各个模块的职责，便于维护和扩展。
4.6 差异化功能（圈钱功能）：宠物助手
圈钱功能是，content/pet-assistant/ 这个模块是项目的差异化功能。它包含了10个子模块，实现了一个可爱的页面悬浮宠物：
-
10种宠物形象（猫、狗、狐狸、熊猫等，1个免费 + 9个高级） -
环形菜单快捷入口 -
自主溜达行为 -
状态动画系统（待机、行走、开心、困倦等） -
需求系统（注意力、活动、休息） -
性格系统（5个维度影响行为）
这个功能在第四篇文章会详细讲解，包括动画系统的实现、性能优化等（纯纯的是因为找不到圈钱项）。
五、写在最后
这是系列的第一篇，主要讲了项目的起源、技术选型和整体架构。希望能让你对浏览器插件开发有个全局的认识。
下一篇我们会深入代码，看看那些核心功能是怎么一步步实现的： – 📸 截图功能：如何使用 chrome.tabs.captureVisibleTab API，如何处理区域选择和图片压缩 – 💾 数据存储：IndexedDB 的初始化、版本管理、数据迁移 – 📨 消息传递：Background 和 Content Script 如何通信，如何处理异步响应。
立即体验
想亲自试试「时间轴随手记」吗？（跪求体验，开发出来没人用啊）
-
🔗 Edge 插件直达： https://microsoftedge.microsoft.com/addons/detail/kbkmnnpkgcjkgoolgklolpeabndocnfd
项目后期会考虑开源，到时候会在公众号第一时间通知大家。
实践建议
如果你也想开发浏览器插件，这里有几个建议：
- 从小项目开始：不要一上来就想做个大而全的插件，从解决一个小问题开始
- 先看官方文档：Chrome Extension 的官方文档写得很好，值得仔细读一遍（直接AI也行）
- 理解运行机制：搞清楚 Background、Content Script、Popup 的区别和通信方式。
- 重视架构设计：好的架构能让后期开发事半功倍。
- 考虑云服务：Cloudflare Workers/Pages 这类服务很适合个人开发者
