---

如果你觉得 MiniMark 有用，欢迎到 GitHub 点个 Star 支持一下！

目录

• 项目简介
• 核心特性
• 界面预览
• 安装方式
• 快速开始
• 同步策略
• 隐私与安全
• 项目结构
• 技术实现
• 开发指南
• 常见问题
• 贡献指南
• 开源协议

项目简介

MiniMark 是一款基于 Manifest V3 的浏览器书签同步扩展。它把书签数据序列化为 JSON，托管到你自己的 GitHub Gist 或 Gitee 代码片段中，借助这两大平台的免费存储实现跨设备、跨浏览器的书签同步。

整个插件追求三件事：简单（零配置即可上手，填入 Token 即用）、免费（无需自建服务器，依托 Gist 存储）、隐私优先（所有个人 Token 仅保存在本地浏览器存储，书签数据加密存储于你私有的 Gist，不经过任何第三方服务器）。

核心特性

特性	说明
双平台支持	同时对接 GitHub Gist 与 Gitee，可自由切换同步对象，互不干扰
双向同步	支持本地上传至远端、远端下载至本地两个方向
两种同步模式	覆盖模式以当前设备为准整体替换；合并模式按 URL 去重，保留两端新增
智能自动同步	定时任务自动比较本地与远端数量，选择更优方向同步，避免覆盖更多数据
状态对比分析	一键检查本地独有、远端独有、两端共有项，并检测书签的顺序 / 位置变化（如重新排序、移动文件夹），差异一目了然
同步趋势	内置近 7 日同步次数柱状图，直观掌握同步频率
历史记录	完整记录每次同步的平台、方向、结果，支持搜索、筛选与分页
书签浏览页	独立页面（nav.html）以层级树形展示全部书签，可快速跳转，便于在弹窗外浏览与管理
自动清理旧片段	启动时清理同名旧 Gist，仅保留最新一份，避免重复堆积
实时未同步提醒	监听书签增删改，书签变动即刻在扩展图标显示角标红点
零依赖	纯原生 JavaScript 实现，无任何前端框架，体积小巧

界面预览

MiniMark 采用 420×600 的卡片化弹窗设计，主色调为清新绿色（#22c55e），整体风格现代简洁。

• 状态总览卡：圆形状态指示、同步进度条、自动同步开关与同步对象标签，一眼掌握当前同步状态
• 三栏统计：本地书签数、远端书签数、差异项数（含顺序/位置变化项），差异卡可点击展开对比详情
• 快速操作：醒目的"本地→远端"上传与"远端→本地"下载双按钮
• 书签浏览：点击状态总览卡中的本地书签数，或主页的浏览入口，打开独立的树形书签浏览页
• 定时同步：iOS 风格开关，可查看下次执行时间
• 健康报告：近 7 天同步异常提示条
• 7 日趋势图：柱状图展示本周每日同步次数，高亮峰值与今日
• 同步仓库：GitHub / Gitee 双仓库卡片，显示分支与书签数，点击直达 Gist 页面
• 同步记录：最近 8 条同步历史，可进入全量视图搜索筛选

安装方式

方式一：开发者模式加载（推荐）

1. 下载或克隆本仓库到本地：

   git clone https://gitcode.com/mininote/MiniMark.git
   

2. 打开 Chrome（或任何 Chromium 内核浏览器，如 Edge、Brave），进入扩展管理页：

   chrome://extensions/
   

3. 打开右上角开发者模式开关。

4. 点击加载已解压的扩展程序，选择本项目的根目录（包含 manifest.json 的文件夹）。

5. 扩展图标出现在工具栏，点击即可使用。

方式二：打包安装

若已发布到 Chrome 应用商店或 Edge Add-ons，可直接通过商店链接安装（发布后在此补充链接）。

快速开始

1. 获取平台 Token

MiniMark 通过 Token 访问你的 Gist，请按需获取：

• GitHub：访问 Personal Access Tokens，生成一个勾选 gist 权限的 Classic Token。
• Gitee：访问 私人令牌，生成一个勾选 gists 权限的令牌。

2. 配置连接

1. 点击扩展图标打开弹窗。
2. 点击右上角设置按钮进入设置页。
3. 在账号连接中粘贴对应平台的 Token，点击验证。验证成功后会显示你的用户名与头像。

3. 选择同步对象

在设置页的同步对象中选择 GitHub 或 Gitee 作为默认同步平台。

4. 开始同步

回到主页，根据需求操作：

• 点击检查状态：对比本地与远端差异，弹窗展示本地独有、远端独有以及顺序/位置变化，内容过多时弹窗内部独立滚动。
• 点击本地 → 远端：将本地书签上传备份。
• 点击远端 → 本地：将远端书签恢复到本地。
• 打开定时同步开关：按设定间隔自动同步。

同步策略

MiniMark 提供两种同步模式，在设置页的同步设置中切换：

覆盖模式（默认）

以当前设备书签为准，整体替换远端（上传时）或本地（下载时）。适合单设备主导、追求强一致的场景。下载恢复时会先清空本地书签栏内容再写入远端数据。

合并模式

按 URL 去重，保留两端各自新增的书签。上传时先将远端书签合并进本地（不删除本地已有项），再整体上传；下载时同样以合并方式写入本地。适合多设备并行使用的场景，最大限度避免书签丢失。

智能自动同步

开启定时同步后，后台任务会自动比较本地与远端书签数量并智能选择方向：

• 远端数量多于本地：从远端下载，避免覆盖更多数据。
• 本地数量不少于远端：上传到远端。

合并模式下则统一执行双向合并，无需比较数量。

隐私与安全

MiniMark 的设计以隐私为前提：

• Token 仅存本地：你的 GitHub / Gitee Token 保存在浏览器的 chrome.storage.local 中，不会上传到任何第三方服务器。
• 书签存储于私有 Gist：同步时创建的 Gist 默认为私有（public: false），仅你本人可见。
• 直连平台 API：所有数据请求直接发往 api.github.com 与 gitee.com，扩展本身不架设任何中转服务。
• 最小权限：仅申请 bookmarks、storage、alarms 三个权限，以及两个平台的网络访问权限。

如需彻底清除数据，可在设置页数据管理中选择清空本地书签或全部重置。

项目结构

MiniMark/
├── manifest.json          # 扩展清单（Manifest V3）
├── background.js          # Service Worker，后台同步逻辑核心
├── popup.html             # 弹窗界面结构
├── popup.css              # 弹窗样式
├── popup.js               # 弹窗交互逻辑
├── nav.html               # 书签浏览页（独立树形浏览界面）
├── nav.css                # 书签浏览页样式
├── nav.js                 # 书签浏览页交互逻辑
├── _locales/              # 多语言资源（仅 manifest 的 name/description 使用）
│   ├── en/messages.json
│   └── zh_CN/messages.json
└── icons/                 # 图标资源
    ├── icon16.png
    ├── icon48.png
    ├── icon128.png
    ├── logo.png
    ├── github.svg
    └── gitee.svg

技术实现

MiniMark 基于 Chrome 扩展 Manifest V3 规范开发，采用纯原生 JavaScript，无任何构建步骤与运行时框架依赖。

• Service Worker（background.js）：承载全部同步核心逻辑，包括 Token 验证、Gist 增删改查、书签树序列化与恢复、智能同步决策、旧片段清理。通过 chrome.alarms 实现定时任务，监听 chrome.bookmarks 事件实时标记未同步状态并更新角标。
• 弹窗界面（popup.*）：负责状态展示与用户交互，通过 chrome.runtime.sendMessage 与后台 Service Worker 通信。采用卡片化栅格布局，iOS 风格开关，内嵌 SVG 图标，无需任何外部图标库。
• 数据存储：所有配置与同步状态通过 chrome.storage.local 持久化，包括 Token、Gist ID、同步历史（保留最近 50 条）、同步间隔等。
• 同步状态分析：将本地与远端书签树扁平化，除比较 URL 集合（交集/差集）外，还为每个书签计算含层级顺序的签名 orderKey，能够检测书签被重新排序或移动到其他文件夹等结构性变化，生成可视化对比报告。

开发指南

本项目无需安装任何依赖，克隆后即可直接加载调试。

1. 克隆仓库并按安装方式加载到浏览器。
2. 在 chrome://extensions/ 页面点击扩展卡片上的详情 → 检查视图，可打开 Service Worker 的 DevTools 进行后台调试。
3. 点击扩展图标打开弹窗后右键检查，可调试弹窗界面。
4. 修改代码后，在扩展管理页点击刷新按钮即可重新加载。

调试技巧：

• 后台日志输出在 Service Worker 的 Console 中。
• chrome.storage.local 的内容可在弹窗 DevTools 的 Application → Storage → Local Storage 中查看。
• 书签数据格式为 { version, timestamp, count, bookmarks }，bookmarks 即 chrome.bookmarks.getTree() 的原始结构。

关于多语言：目前仅 manifest.json 的 name / description 走 _locales 国际化占位符，弹窗与浏览页 UI 为硬编码中文。后续若要做完整中英文界面，需改造 popup.* / nav.*。

常见问题

Q：同步时报"Gitee 数据过大"怎么办？

Gitee 限制单个 Gist 文件最大 1MB。当书签数据超过此限制时会中断同步，建议改用 GitHub（无此限制）或精简书签数量。

Q：Gitee 同步后书签标题里的 emoji 消失了？

Gitee 的数据库不支持 4 字节 UTF-8 字符（大部分 emoji），写入会报错。MiniMark 在上传 Gitee 前会自动剥离这类字符以保证同步成功，GitHub 则完整保留。

Q：换了一台电脑，如何恢复书签？

在新设备安装扩展并配置同一平台的 Token，进入主页点击远端 → 本地即可恢复。覆盖模式下会先清空本地再写入远端数据。

Q：自动同步会覆盖我新加的书签吗？

智能自动同步会比较两端数量，选择数据更多的一端为准，尽量避免丢失。若多设备并行使用，建议切换为合并模式，按 URL 去重保留两端新增。

Q：Token 会泄露吗？

Token 仅存储在本地浏览器，所有请求直连 GitHub / Gitee 官方 API，扩展不经过任何第三方服务。Gist 默认创建为私有，仅你本人可见。

贡献指南

欢迎通过 Issue 和 Pull Request 参与本项目。

1. Fork 本仓库。
2. 创建你的特性分支：git checkout -b feature/your-feature。
3. 提交更改：git commit -m 'Add some feature'。
4. 推送分支：git push origin feature/your-feature。
5. 提交 Pull Request 并描述你的改动。

提交前请确保：

• 代码风格与现有保持一致（原生 JavaScript，无框架依赖）。
• 不引入新的运行时依赖。
• 涉及 UI 改动时保持 420×600 弹窗尺寸内的良好显示效果。

开源协议

本项目采用 MIT License 开源协议。如需在项目中使用，请遵循协议要求保留版权声明。