# Obsidian Web Clipper 完全研究

> Obsidian 官方网页剪存插件：高亮与捕获网页内容
>
> 归档：2026-04-25

---

## 📊 项目概览

| 属性 | 值 |
|------|---|
| **仓库** | obsidianmd/obsidian-clipper |
| **定位** | Obsidian 官方网页剪存浏览器扩展 |
| **技术栈** | TypeScript + Web Extension |
| **许可** | 官方开源 |
| **安装** | Chrome / Firefox / Safari / Edge |

---

## 🎯 核心定位

```
网页内容 → Web Clipper 浏览器扩展 → 转换为 Markdown → 保存到 Obsidian Vault
```

**关键特点**：
- 存储为**持久的 Markdown 文件**，可离线阅读
- 长期保存，不受网站变更影响
- 支持高亮标注
- 支持模板自定义

---

## 🌐 浏览器支持

| 浏览器 | 安装渠道 |
|--------|---------|
| **Chrome / Brave / Arc** | Chrome Web Store |
| **Firefox / Firefox Mobile** | Firefox Add-Ons |
| **Safari (macOS/iOS/iPadOS)** | App Store |
| **Microsoft Edge** | Edge Add-Ons |

---

## 🔧 核心功能

### 1. 内容捕获

- 提取网页正文内容
- 自动转换为 Markdown
- 保留链接和图片引用

### 2. 高亮标注

- 在网页上直接选中文本高亮
- 高亮内容保存为笔记的一部分
- 可添加注释

### 3. 模板系统

- 自定义剪存笔记格式
- 支持变量（日期、标题、URL 等）
- 模板压缩存储（lz-string）

### 4. 过滤器

- 按 CSS 选择器过滤页面元素
- 排除不需要的内容
- 精确控制捕获范围

### 5. 本地图片保存

- Obsidian 1.8.0+ 支持
- 网页图片自动下载到本地
- 不依赖外部链接

---

## 🏗️ 技术架构

### 核心依赖

| 依赖 | 用途 |
|------|------|
| **webextension-polyfill** | 跨浏览器兼容 |
| **defuddle** | 内容提取 + Markdown 转换 |
| **dayjs** | 日期解析和格式化 |
| **lz-string** | 模板压缩，减少存储空间 |
| **lucide** | 图标库 |
| **dompurify** | HTML 清理，安全防护 |

### 构建输出

```
npm run build
  ↓
dist/        → Chromium 版本
dist_firefox/ → Firefox 版本
dist_safari/  → Safari 版本
```

---

## 🆚 与其他剪存工具对比

| 工具 | 输出格式 | 离线可用 | 开源 | 生态 |
|------|---------|---------|------|------|
| **Obsidian Web Clipper** | Markdown | ✅ | ✅ | Obsidian |
| **Evernote Web Clipper** | 专有格式 | ❌ | ❌ | Evernote |
| **Notion Web Clipper** | Notion Block | ✅ | ❌ | Notion |
| **Joplin Web Clipper** | Markdown | ✅ | ✅ | Joplin |
| **Logseq Web Clipper** | Markdown | ✅ | ✅ | Logseq |

---

## 💡 使用场景

| 场景 | 说明 |
|------|------|
| 研究资料收集 | 保存网页文章到知识库 |
| 读书笔记 | 保存在线书籍内容 |
| 代码片段 | 保存技术博客和教程 |
| 灵感收集 | 快速捕获灵感网页 |
| 长期存档 | 防止网页内容失效 |

---

## 🔗 与 Obsidian Desktop/Mobile 的区别

| 特性 | Web Clipper | Obsidian App |
|------|------------|-------------|
| **平台** | 浏览器扩展 | 桌面/手机应用 |
| **用途** | 从网页捕获内容 | 编辑和管理笔记 |
| **存储** | 直接写入 Vault | 本地文件系统 |
| **同步** | 依赖 Vault 同步 | 支持多端同步 |

---

## 📝 模板示例

```markdown
---
title: {{title}}
url: {{url}}
date: {{date}}
tags:
---

# {{title}}

{{content}}

---
*Clipped from {{url}}*
```

### 可用变量

| 变量 | 说明 |
|------|------|
| `{{title}}` | 网页标题 |
| `{{url}}` | 网页 URL |
| `{{date}}` | 剪存日期 |
| `{{content}}` | 网页内容 |
| `{{selection}}` | 选中的文本 |

---

## 🔧 本地开发

### 安装步骤

```bash
# 克隆仓库
git clone https://github.com/obsidianmd/obsidian-clipper.git
cd obsidian-clipper

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test
```

### Chrome 加载

1. 打开 `chrome://extensions`
2. 启用开发者模式
3. 点击"加载已解压的扩展程序"
4. 选择 `dist/` 目录

### Firefox 加载

1. 打开 `about:debugging#/runtime/this-firefox`
2. 点击"临时加载附加组件"
3. 选择 `dist_firefox/manifest.json`

---

## 🚀 路线图（待开发功能）

| 功能 | 状态 |
|------|------|
| 高亮注释 | ✅ 已完成 |
| 模板目录 | ✅ 已完成 |
| 本地图片保存 | ✅ 已完成 (Obsidian 1.8.0+) |
| 模板验证 | 计划中 |
| 模板逻辑 (if/for) | 计划中 |
| 更多语言翻译 | 进行中 |

---

## 💡 与 Obsidian 插件的区别

| 维度 | Web Clipper | Obsidian 插件 |
|------|------------|-------------|
| **运行位置** | 浏览器 | Obsidian 应用内 |
| **功能** | 网页→笔记 | 增强笔记编辑 |
| **安装** | 浏览器扩展商店 | Obsidian 社区插件市场 |
| **依赖** | 独立运行 | 依赖 Obsidian |

---

## 🔗 资源

| 资源 | 链接 |
|------|------|
| **GitHub** | https://github.com/obsidianmd/obsidian-clipper |
| **官方下载** | https://obsidian.md/clipper |
| **帮助文档** | https://help.obsidian.md/web-clipper |
| **Chrome 安装** | https://chromewebstore.google.com/detail/obsidian-web-clipper/cnjifjpddelmedmihgijeibhnjfabmlf |
| **Firefox 安装** | https://addons.mozilla.org/en-US/firefox/addon/web-clipper-obsidian/ |
| **Safari 安装** | https://apps.apple.com/us/app/obsidian-web-clipper/id6720708363 |
| **Edge 安装** | https://microsoftedge.microsoft.com/addons/detail/obsidian-web-clipper/eigdjhmgnaaeaonimdklocfekkaanfme |

---

## 📊 评价

### 优点
- ✅ **官方出品**：与 Obsidian 深度集成
- ✅ **Markdown 优先**：输出持久化、可离线
- ✅ **多浏览器支持**：Chrome / Firefox / Safari / Edge
- ✅ **高亮标注**：网页内容直接标记
- ✅ **模板自定义**：灵活控制笔记格式
- ✅ **开源**：社区可贡献

### 注意点
- ⚠️ 需要配合 Obsidian 桌面端使用
- ⚠️ 模板功能相对简单（不支持 if/for）
- ⚠️ 移动端支持有限（仅 Safari iOS/iPadOS）

### 适用场景
- 需要将网页内容保存到 Obsidian 知识库
- 希望内容以 Markdown 格式长期保存
- 需要高亮标注功能
- 跨浏览器使用场景

---

*整理：知识库管理员 | 归档：2026-04-25*