# VeilCrawler

**Repository Path**: erma0/VeilCrawler

## Basic Information

- **Project Name**: VeilCrawler
- **Description**: 轻量可视化通用web数据采集插件
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VeilCrawler - 可视化 Web 数据采集助手

![VeilCrawler Logo](src/icons/logo.svg)

## 💡 项目背景与技术选型

### 初衷：解决“所见即不可得”的痛点

VeilCrawler 的诞生源于一次对抖音 Web 端数据的采集需求。现代网页（如抖音、快手、小红书 等）的反爬虫机制相对复杂，传统的 HTTP 请求模拟（requests）面临着巨大的挑战：

- **复杂的参数签名 (Signature)**: JS 混淆、环境检测。
- **高强度的加密 (Encryption)**: 请求体和响应体加密。

### 技术选型

为了绕过逆向工程的泥潭，通过AI进行全方位分析对比，我最终选择了 **Python** + **Browser CDP** 模式，基于 **[DrissionPage](https://github.com/g1879/DrissionPage)** 或 **[nodriver](https://github.com/ultrafunkamsterdam/nodriver)** 等自带反爬的库来开发采集引擎，避开 WebDriver 特征检测，拥有完整的系统权限（文件读写、进程控制）。

本项目主要是实现 **浏览器扩展 (Extension)** 方案 —— 直接利用浏览器渲染好的 DOM 和已签名的网络请求，这解决了“获取数据”的问题。

然而，单纯的浏览器扩展受限于沙箱环境 (Sandbox) 和文件系统权限，难以实现复杂的数据后处理（如批量下载无水印视频、大规模并发采集、自动化调度）。

因此，目前 **VeilCrawler 定位为一款轻量级的“浏览器数据采集插件”**。

## 🤝 同类项目对比分析

_注：本分析由 AI 生成，仅供参考。_

| 维度           | **VeilCrawler (本项目)**          | **Web Scraper** / **Data Scraper** | **八爪鱼** / **后羿采集器** | **Python/Node.js 脚本**  |
| :------------- | :-------------------------------- | :--------------------------------- | :-------------------------- | :----------------------- |
| **类型**       | 开源浏览器扩展                    | 浏览器扩展                         | 商业桌面软件                | 编程脚本                 |
| **上手难度**   | ⭐ (极低)                         | ⭐⭐ (中等)                        | ⭐ (低，但界面复杂)         | ⭐⭐⭐⭐⭐ (高)          |
| **反爬能力**   | ⭐⭐⭐ (基于浏览器，天然绕过签名) | ⭐⭐⭐                             | ⭐⭐⭐ (内置浏览器)         | ⭐ (需自行处理签名/指纹) |
| **自动验证码** | ❌ **不支持** (需人工辅助)        | ❌ 不支持                          | ✅ 支持 (部分付费功能)      | ✅ 支持 (需对接打码平台) |
| **轻量级**     | ✅ 侧边栏沉浸式体验               | ❌ 独立的 DevTools 面板            | ❌ 庞大的安装包             | ✅ 代码轻量              |
| **API 拦截**   | ✅ **支持 (重点特性)**            | ❌ 仅支持 DOM                      | ❌ 较弱                     | ✅ 支持 (需逆向)         |
| **数据后处理** | ❌ 弱 (受限沙箱)                  | ❌ 弱                              | ✅ 强 (内置清洗/导出)       | ✅ 强 (任意库支持)       |
| **费用**       | **完全免费开源**                  | 基础免费 / 高级付费                | 免费限制多 / 订阅昂贵       | 免费                     |

**VeilCrawler 的独特优势**:

1.  **侧边栏交互**: 不占用空间，操作更符合直觉。
2.  **API 优先**: 特别强化对 JSON API 的拦截与解析（不止专注于 DOM）。

## 📸 界面预览

> ![配置界面](static/ui.png)

## 🌐 支持平台

VeilCrawler 基于 **Manifest V3** 标准开发，支持所有基于 **Chromium** 内核的现代浏览器：

- ✅ **Google Chrome** (推荐)
- ✅ **Microsoft Edge**
- ✅ **Brave**
- ✅ **Arc**
- ✅ 其他 Chromium 内核浏览器

## ✨ 核心功能

- **🎯 可视化元素选择**:
  - 鼠标点击页面元素，自动生成 CSS/XPath 选择器。
  - 支持选择文本、HTML、链接 (href)、图片 (src) 等属性。
  - 智能高亮预览，所见即所得。
- **📋 多任务管理**:
  - 创建、编辑、删除多个采集任务。
  - 任务配置自动保存到本地存储。
  - 支持**导入/导出**任务配置（单个或批量备份），便于分享和迁移。
- **🔄 智能翻页系统**:
  - **滚动翻页**: 自动滚动页面加载更多数据（适用于无限滚动页面）。
  - **点击翻页**: 可视化选择“下一页”按钮，自动点击翻页。
  - 支持自定义翻页间隔和最大采集数量限制。
- **🧹 数据清洗与去重**:
  - **智能去重**: 默认开启去重功能，防止重复采集。
  - **自定义主键**: 支持指定一个或多个字段作为“联合主键”，精准控制去重逻辑。
- **📡 JSON API 拦截**:
  - 拦截页面发出的 Ajax 请求。
  - 可视化浏览 JSON 响应结构。
  - 点击 JSON 字段自动生成提取规则（适用于前后端分离网站）。
- **💾 数据导出**:
  - 支持导出为 **JSON** 或 **CSV** 格式。
  - 支持一键复制到剪贴板。

## 🚀 安装指南

### 方式一：下载已发布版本 (推荐)

如果您不想自行编译代码，可以直接下载 Release 页面发布的安装包。

1.  前往本项目的 **[Releases 页面](https://github.com/erma0/VeilCrawler/releases)**。
2.  下载最新版本的 `.crx` 文件或 `dist.zip` 压缩包。
3.  **安装步骤**:
    - 打开 Chrome 浏览器，在地址栏输入 `chrome://extensions/` 并回车。
    - 在右上角开启 **"开发者模式" (Developer mode)**。
    - **如果是 .crx 文件**: 将下载的文件直接拖拽到该页面即可安装（部分新版 Chrome 可能限制拖拽安装，建议使用压缩包）。
    - **如果是 .zip 文件**: 解压文件，点击页面左上角的 **"加载已解压的扩展程序"**，选择解压后的文件夹。

### 方式二：源码编译安装 (开发者)

#### 前置要求

- [Node.js](https://nodejs.org/) (推荐 v16+)
- [pnpm](https://pnpm.io/) (推荐) 或 npm/yarn

### 1. 下载源码并安装依赖

```bash
git clone https://github.com/erma0/VeilCrawler.git
cd VeilCrawler
pnpm install
```

### 2. 构建扩展

```bash
pnpm build
```

构建完成后，会在项目根目录生成 `dist` 文件夹。

### 3. 加载到 Chrome

1.  打开 Chrome 浏览器，访问 `chrome://extensions/`。
2.  在右上角开启 **"开发者模式"**。
3.  点击左上角的 **"加载已解压的扩展程序"**。
4.  选择项目目录下的 `dist` 文件夹。

## 📖 使用手册

### 模式一：DOM 元素采集 (推荐)

1.  **打开面板**: 点击浏览器右上角的 VeilCrawler 图标打开侧边栏面板。
2.  **新建任务**: 点击 `+` 号，输入任务名称和目标网址（或直接使用当前页面）。
3.  **选择元素**:
    - 进入“配置”标签页。
    - 点击 **"选择元素"** 按钮。
    - 鼠标移动到页面上想要采集的数据（如商品标题），点击选中。
    - 在面板中修改字段名称（如 `title`），选择属性（如 `innerText`）。
    - 重复此步骤添加价格、图片等其他字段。
4.  **设置翻页 (可选)**:
    - 在“翻页模式”中选择 **"点击"** 或 **"滚动"**。
    - 如果是点击翻页，点击 **"选取"** 按钮，然后在页面上点击“下一页”按钮。
5.  **运行采集**:
    - 点击 **"运行采集"**。
    - 扩展会自动翻页并收集数据。
    - 采集完成后，可以预览数据并导出。

### 模式二：JSON API 采集 (推荐用于动态网站)

> 适用于前后端分离、数据由 AJAX 请求加载的动态网站。相比 DOM 采集，直接采集 API 数据通常更纯净、更稳定。

1.  **切换模式**: 在任务配置页顶部，切换数据源为 **"JSON 数据"**。
2.  **设置拦截**:
    - 输入 **"拦截 URL"** 特征词（支持 `*` 通配符）。
    - 例如：目标接口为 `https://api.example.com/v1/products?page=1`，可填 `/products` 或 `*/api/products*`。
    - 点击 **"开始"** 按钮启用拦截。
3.  **捕获请求**:
    - 手动刷新当前网页或手动翻页获取新数据。
    - 在面板的“网络请求”列表中会显示拦截到的符合规则的请求。
    - 点击某个请求，下方会展开其 JSON 响应结构。
4.  **配置字段**:
    - 在 JSON 树形视图中，展开节点寻找目标数据。
    - 点击想要采集的字段（如 `title`, `price`），或点击右侧出现的 **"+ 选择"** 按钮。
    - 系统会自动生成提取路径（如 `data.list[*].title`）。
5.  **运行采集**:
    - **自动刷新**: 如果开启了“刷新”选项，点击运行后系统会自动刷新页面以从头开始采集，若关闭此选项则从当前位置继续采集（此时需手动触发一次请求，如翻页或点击某按钮弹出数据页）。
    - **翻页支持**: JSON 模式同样支持“点击”或“滚动”翻页。配置翻页后，系统会在翻页动作触发新请求时自动拦截并提取数据。

### 💾 备份与迁移 (导入/导出)

#### 1. 批量备份 (推荐)
- **导出**: 点击任务列表上方的 **"📦" (批量导出)** 按钮，系统会将当前所有任务及其规则打包成一个 `.json` 文件。
- **用途**: 适用于全量数据备份，防止浏览器缓存清除导致数据丢失。

#### 2. 单个任务分享
- **导出**: 在任务卡片上，点击 **"下载"** 图标。
- **用途**: 生成仅包含该任务配置的 `.json` 文件，方便发送给同事或在不同设备间迁移特定任务。

#### 3. 导入配置
- **本地导入**: 点击任务列表上方的 **"上传"** 图标，选择备份的 `.json` 文件即可恢复。
- **URL 导入**: 点击 **"🔗"** 图标，输入远程 JSON 文件的 URL（需支持跨域访问），可直接加载配置。

### 🔧 进阶技巧

#### 1. 数据去重与主键

默认情况下，VeilCrawler 会对采集到的数据进行去重。

- **自动去重**: 系统会比较每一行数据的所有字段。
- **自定义主键**: 在字段配置列表中，你可以勾选一个或多个字段的“主键”选项。勾选后，系统将仅根据这些字段的组合值来判断数据是否重复（例如仅根据 `id` 或 `url` 去重）。

#### 2. 翻页模式选择

- **滚动翻页**: 适合“瀑布流”网站（如小红书笔记列表、图片站）。
- **点击翻页**: 适合有明确“下一页”按钮的网站（如传统的电商列表、论坛）。
- **间隔设置**: 建议保留为空（智能模式），系统会自动检测网络请求和 DOM 变化。如果遇到采集过快或卡顿，可手动设置固定间隔（如 `1000` ms）。

## ❓ 常见问题 (FAQ)

**Q: 为什么在 JSON 模式下拦截不到请求？**
A: 请检查以下几点：

1. 拦截 URL 是否正确？尝试使用更短的关键词或 `*` 通配符。
2. 是否点击了“开始”拦截按钮？
3. 页面是否真的发送了 XHR/Fetch 请求？部分网站可能使用 SSR（服务端渲染），此时请使用 DOM 模式采集。

**Q: 为什么采集到的数据是空的？**
A:
- **DOM 模式**: 可能是选择器失效，或者页面结构发生了变化。尝试重新选择元素。
- **JSON 模式**: 可能是提取路径错误。请确保预览区域能看到数据。

**Q: 如何导出所有任务配置？**
A: 在任务列表页，点击上方的“批量导出备份”按钮（📦 图标），可以生成包含所有任务和规则的 JSON 文件。

## 🔒 隐私声明

VeilCrawler 是一款**本地优先**的浏览器扩展：

- **数据存储**: 所有采集规则和采集到的数据均存储在您的浏览器本地 (`chrome.storage.local`)。
- **网络通信**: 扩展仅拦截您指定的网站请求以进行数据提取，**绝不会**将您的数据上传到任何第三方服务器。
- **代码开源**: 本项目完全开源，欢迎审查代码以确保安全。
  。

## ⚠️ 免责声明

本工具仅供**技术研究和学习**使用，旨在简化合法的数据采集流程。

1.  **合法合规**: 请勿使用本工具从事任何非法活动（如侵犯个人隐私、窃取商业机密、破坏网站服务等）。
2.  **遵守协议**: 在采集网站数据时，请务必遵守目标网站的 `robots.txt` 协议及相关服务条款 (ToS)。
3.  **责任自负**: 使用者需自行承担因使用本工具而产生的一切法律责任。作者不对任何因使用本工具导致的损失或法律纠纷负责

## 🛠️ 开发指南

```bash
# 安装依赖
pnpm install

# 监听模式开发 (文件变更自动重新构建)
pnpm dev

# 生产环境构建
pnpm build
```

### 项目结构

```
src/
├── popup/          # 侧边栏/弹窗 UI (React)
│   ├── App.tsx     # 主应用逻辑
│   ├── main.tsx
│   └── styles.css
├── content/        # Content Script (页面注入脚本)
│   └── index.ts    # 处理元素选择、高亮、DOM 数据提取
├── background/     # Service Worker
│   └── index.ts    # 处理跨域请求、Tab 管理
├── injected/       # 注入页面的拦截脚本
│   └── interceptor.ts # XHR/Fetch 拦截
├── utils/          # 工具函数
├── icons/          # 图标资源
├── types.ts        # TypeScript 类型定义
└── manifest.json   # Chrome 扩展清单 V3
```

## 📝 待办事项 (Roadmap)

- [x] DOM 元素可视化选择
- [x] 自动翻页 (点击/滚动)
- [x] 数据预览与导出 (JSON/CSV)
- [x] 任务导入/导出功能
- [x] 数据去重与主键设置
- [x] JSON API 模式拦截与提取
- [ ] 定时采集任务

## 📄 License

MIT