# bookmarkSyncGitee

**Repository Path**: tuminghui/bookmarkSyncGitee

## Basic Information

- **Project Name**: bookmarkSyncGitee
- **Description**: chromeExtensions chrome插件 将 书签同步 gitee 仓库  
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2023-11-21
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<img src="AppreciationQRCode.jpg" width="580" height="580">
# BookmarkSyncGitee

一个 Chrome 浏览器扩展程序，用于将浏览器书签同步到 Gitee 仓库。通过 Gitee 仓库作为云端存储，实现书签的备份和多设备同步。

## ✨ 核心功能

- 📤 **书签上传**：将 Chrome 浏览器的所有书签导出为 JSON 格式，经过 Base64 编码后上传到 Gitee 仓库
- 📥 **书签拉取**：从 Gitee 仓库下载书签数据，解码后恢复到 Chrome 浏览器（支持差集合并，保留文件夹结构）
- 🗑️ **书签去重**：自动扫描本地书签，找出相同 URL 的重复书签，保留最新创建的书签，删除其他重复项（Vue 版本支持）
- ⚙️ **配置管理**：安全保存 Gitee 仓库信息和访问令牌，支持一键配置和清除
- 🔄 **自动同步**：监控书签变化事件，自动同步到 Gitee（Vue 版本支持）
  - 监听书签创建、修改、删除、移动、顺序改变等事件
  - 使用防抖机制，避免频繁操作导致多次同步
  - 5 秒延迟自动同步，确保数据一致性

## 📁 项目结构

本项目包含两个版本的实现：

```
bookmarkSyncGitee/
├── jquery/                    # jQuery 版本（原生实现）
│   ├── src/                  # 源代码目录
│   │   ├── manifest.json     # 扩展配置
│   │   ├── popup.html        # 弹窗界面
│   │   ├── background.js     # 后台脚本
│   │   ├── js/              # JavaScript 文件
│   │   ├── css/             # 样式文件
│   │   └── img/             # 图标资源
│   └── README.md            # jQuery 版本说明
│
├── Vue/                      # Vue 3 版本（现代化实现）
│   ├── src/                 # Vue 源代码
│   │   ├── components/      # Vue 组件
│   │   ├── utils/           # 工具函数
│   │   └── main.js          # 入口文件
│   ├── background.js        # 后台服务脚本
│   ├── manifest.json        # 扩展配置
│   ├── package.json         # 项目依赖
│   └── README.md            # Vue 版本说明
│
└── README.md                # 本文件
```

## 🚀 快速开始

### 方式一：使用 jQuery 版本（简单直接）

1. **克隆仓库**
   ```bash
   git clone https://gitee.com/tuminghui/bookmarkSyncGitee.git
   cd bookmarkSyncGitee
   ```

2. **加载扩展**
   - 打开 Chrome 浏览器，输入 `chrome://extensions/`
   - 打开右上角的"开发者模式"
   - 点击"加载已解压的扩展程序"
   - 选择 `jquery/src` 目录

3. **配置 Gitee**
   - 在 Gitee 上创建一个仓库（公开或私有均可）
   - 在 Gitee 个人设置中生成 access_token（需要 `projects` 权限）
   - 点击扩展图标，输入仓库 URL 和 access_token，点击"设置"

### 方式二：使用 Vue 版本（推荐，功能更丰富）

1. **克隆仓库**
   ```bash
   git clone https://gitee.com/tuminghui/bookmarkSyncGitee.git
   cd bookmarkSyncGitee/Vue
   ```

2. **安装依赖**
   ```bash
   npm install
   ```

3. **构建项目**
   ```bash
   npm run build
   ```

4. **加载扩展**
   - 打开 Chrome 浏览器，输入 `chrome://extensions/`
   - 打开右上角的"开发者模式"
   - 点击"加载已解压的扩展程序"
   - 选择 `Vue/dist` 目录

5. **配置 Gitee**
   - 在扩展弹窗中配置 Gitee 仓库信息
   - 启用"自动同步"开关（可选）

## 📖 使用说明

### 基本操作

1. **首次使用**
   - 注册 Gitee 账号并创建仓库
   - 生成 access_token（设置 → 安全设置 → 私人令牌）
   - 在扩展弹窗中配置仓库 URL 和 access_token

2. **上传书签**
   - 点击扩展图标
   - 点击"提交"按钮
   - 等待上传完成通知

3. **拉取书签**
   - 点击扩展图标
   - 点击"拉取"按钮
   - 系统会计算 Gitee 和本地书签的差集，只添加本地不存在的书签
   - 自动保持文件夹结构，智能创建缺失的文件夹
   - ⚠️ **注意**：拉取操作不会删除本地已有书签，只添加新书签

4. **去重书签**（Vue 版本）
   - 点击扩展图标
   - 点击"去重"按钮
   - 系统会扫描所有本地书签，找出相同 URL 的重复书签
   - 对于每个重复的 URL，保留最新创建的书签，删除其他重复项
   - ⚠️ **注意**：删除操作不可恢复，建议先备份书签

### 自动同步功能（Vue 版本）

启用"自动同步"开关后，扩展会监控以下书签变化：

- ✅ 创建新书签
- ✅ 修改书签（标题/URL）
- ✅ 移动书签
- ✅ 删除书签
- ✅ 改变书签顺序

所有变化会在 5 秒后自动同步到 Gitee，使用防抖机制避免频繁操作。

详细说明请查看：[自动同步功能指南](./Vue/AUTO_SYNC_GUIDE.md)

## 🔧 技术栈

### jQuery 版本
- HTML + CSS + jQuery
- Chrome Extension Manifest V3
- Chrome Storage API
- Gitee API v5

### Vue 版本
- Vue 3
- Vue CLI 5
- Chrome Extension Manifest V3
- Chrome Storage API
- Gitee API v5

## 📋 功能对比

| 功能 | jQuery 版本 | Vue 版本 |
|------|------------|---------|
| 书签上传 | ✅ | ✅ |
| 书签拉取 | ✅ | ✅（支持差集合并） |
| 书签去重 | ❌ | ✅ |
| 配置管理 | ✅ | ✅ |
| 清除配置 | ❌ | ✅ |
| 自动同步 | ❌ | ✅ |
| 书签变化监控 | ❌ | ✅ |
| 启动时自动合并 | ❌ | ✅ |
| 现代化 UI | ❌ | ✅ |
| 组件化开发 | ❌ | ✅ |
| Web Worker 支持 | ❌ | ✅ |

## 🛠️ 开发说明

### jQuery 版本开发

直接修改 `jquery/src` 目录下的文件即可，无需构建。

### Vue 版本开发

1. **开发模式**
   ```bash
   cd Vue
   npm run serve
   ```

2. **构建生产版本**
   ```bash
   npm run build
   ```

3. **代码检查**
   ```bash
   npm run lint
   ```

4. **重新加载扩展**
   - 修改代码后重新构建
   - 在 Chrome 扩展管理页面点击"重新加载"按钮

## 📚 文档

### Vue 版本文档

- [README.md](./Vue/README.md) - Vue 版本使用说明
- [AUTO_SYNC_GUIDE.md](./Vue/AUTO_SYNC_GUIDE.md) - 自动同步功能指南
- [BOOKMARK_MONITORING.md](./Vue/BOOKMARK_MONITORING.md) - 书签监控功能说明
- [CHROME_BOOKMARK_EVENTS.md](./Vue/CHROME_BOOKMARK_EVENTS.md) - Chrome 书签事件 API 文档
- [BUILD_TROUBLESHOOTING.md](./Vue/BUILD_TROUBLESHOOTING.md) - 构建问题排查
- [ERROR_SOLUTIONS.md](./Vue/ERROR_SOLUTIONS.md) - 错误解决方案

### jQuery 版本文档

- [README.md](./jquery/README.md) - jQuery 版本使用说明

## ⚠️ 注意事项

1. **数据安全**
   - access_token 存储在 Chrome Storage 中，请妥善保管
   - 建议使用私有仓库存储书签数据

2. **拉取操作**（Vue 版本）
   - 拉取书签时不会删除本地已有书签，只添加新书签
   - 自动保持文件夹结构，智能创建缺失的文件夹
   - 基于 URL 进行差集比较，避免重复添加

3. **去重操作**（Vue 版本）
   - 去重操作会永久删除重复的书签，不可恢复
   - 建议在执行去重前先上传备份到 Gitee
   - 保留最新创建的书签（dateAdded 最大）

3. **权限要求**
   - access_token 需要 `projects` 权限才能操作仓库文件
   - 扩展需要 `bookmarks` 权限访问书签

4. **文件格式**
   - 书签数据以 JSON 格式存储在 Gitee 仓库的 `bookmark.json` 文件中
   - 数据使用 Base64 编码传输

5. **网络要求**
   - 需要能够访问 Gitee API（`https://gitee.com/api/v5/`）
   - 自动同步功能需要稳定的网络连接

## 🔍 调试

### 查看日志

1. **扩展弹窗日志**
   - 右键点击扩展图标
   - 选择"检查弹出内容"
   - 查看控制台日志

2. **后台脚本日志**
   - 打开 `chrome://extensions/`
   - 找到本扩展
   - 点击"service worker"链接
   - 查看控制台日志

### 常见问题

- **同步失败**：检查网络连接和 Gitee 配置
- **权限错误**：确认 access_token 有 `projects` 权限
- **构建错误**：查看 [BUILD_TROUBLESHOOTING.md](./Vue/BUILD_TROUBLESHOOTING.md)

## 🤝 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 📄 许可证

详见 [LICENSE](./jquery/LICENSE) 文件

## 🔗 相关链接

- [Chrome 扩展程序开发指南](https://developer.chrome.com/extensions/getstarted)
- [Chrome 扩展程序开发入门](https://segmentfault.com/a/1190000010107732)
- [Gitee API v5 文档](https://gitee.com/api/v5/swagger)
- [Vue 3 官方文档](https://vuejs.org/)
- [Chrome Bookmarks API](https://developer.chrome.com/docs/extensions/reference/bookmarks/)

## 📝 更新日志

### Vue 版本 v0.2.0
- ✅ 新增书签去重功能
- ✅ 优化拉取功能，支持差集合并和文件夹结构保持
- ✅ 新增清除配置功能
- ✅ 优化提交和拉取功能，使用 Web Worker 提升性能
- ✅ 修复 404 错误处理，支持自动创建文件
- ✅ 优化 UI 布局，修复滚动条问题

### Vue 版本 v0.1.0
- ✅ 实现书签上传功能
- ✅ 实现书签拉取功能
- ✅ 实现配置管理功能
- ✅ 实现自动同步功能
- ✅ 实现书签变化监控
- ✅ 现代化 UI 设计

### jQuery 版本 v0.0.1
- ✅ 实现书签上传功能
- ✅ 实现书签拉取功能
- ✅ 实现配置管理功能

---

**⭐ 如果这个项目对你有帮助，欢迎 Star！**