npm package: @raphaellcs/web-scraper
Description: Web 抓取工具 - 代理支持、数据转换、批量处理
Author: 梦心
Latest version: 2.0.0

# @raphaellcs/web-scraper
[![npm](https://img.shields.io/npm/v/@raphaellcs/web-scraper)](https://www.npmjs.com/package/@raphaellcs/web-scraper)
[![downloads](https://img.shields.io/npm/dm/@raphaellcs/web-scraper)](https://www.npmjs.com/package/@raphaellcs/web-scraper)
[![license](https://img.shields.io/npm/l/@raphaellcs/web-scraper)](https://www.npmjs.com/package/@raphaellcs/web-scraper)

> Web 抓取工具 - 简单的网页数据提取

## 🚀 功能

- **CSS 选择器**：使用熟悉的 CSS 语法选择元素
- **属性提取**：提取链接、图片等元素的属性
- **批量抓取**：支持抓取多个页面
- **多种格式**：JSON、CSV、TXT 输出
- **延迟控制**：避免请求过快被封
- **自定义请求头**：模拟浏览器请求
- **代理支持**：支持 HTTP/HTTPS 代理（新）
- **User-Agent 轮换**：9种常见浏览器 UA 自动轮换（新）
- **代理池**：自动选择代理，失败重试（新）
- **数据转换**：类型转换、验证、过滤、聚合（新）
- **去重功能**：支持字段和对象去重（新）

## 📦 安装

```bash
npx @claw-dev/web-scraper
```

## 📖 快速开始

### 1. 命令行抓取

```bash
web-scraper scrape https://example.com -s "h1,p,a" -a "href"
```

### 2. 配置文件

生成配置：

```bash
web-scraper init
```

编辑 `web-scraper.json`：

```json
{
  "url": "https://example.com",
  "selectors": ["h1", "h2", "p", "a"],
  "attributes": ["href", "src", "alt"],
  "options": {
    "saveHtml": true,
    "delay": 1000
  }
}
```

运行：

```bash
web-scraper run
```

## 📋 配置说明

### 选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-s, --selectors` | CSS 选择器（逗号分隔） | `h1,h2,h3,p,a,img` |
| `-a, --attributes` | 提取属性（逗号分隔） | - |
| `-H, --headers` | 请求头（JSON 格式） | - |
| `-t, --timeout` | 超时时间（毫秒） | `30000` |
| `-l, --limit` | 限制显示数量 | - |
| `--html` | 保存 HTML 内容 | `false` |
| `-o, --output` | 保存到文件 | - |
| `--format` | 输出格式（json/csv/txt） | `json` |
| `-p, --proxy` | 使用代理（格式：protocol://host:port） | - |
| `-u, --user-agent` | 自定义 User-Agent | - |
| `--rotate-user-agent` | 轮换 User-Agent | `false` |

### 数据转换命令

| 参数 | 说明 |
|------|------|
| `<input>` | 输入文件（JSON 格式）|
| `-o, --output` | 保存到文件 |
| `--rules <json>` | 转换规则（JSON 格式）|
| `--filter <json>` | 过滤条件（JSON 格式）|
| `--dedup <field>` | 去重字段 |
| `--aggregate <json>` | 聚合规则（JSON 格式）|

### 代理测试命令

| 参数 | 说明 |
|------|------|
| `<proxy>` | 代理地址（格式：protocol://host:port）|
| `-u, --url` | 测试 URL（默认：https://httpbin.org/ip）|

## 🎯 使用场景

### 1. 抓取新闻标题

```bash
web-scraper scrape https://news.example.com -s "h2.title"
```

### 2. 提取所有链接

```bash
web-scraper scrape https://example.com -s "a" -a "href"
```

### 3. 抓取产品信息

```bash
web-scraper scrape https://shop.example.com \
  -s "div.product" \
  -a "data-id,data-price"
```

### 4. 批量抓取

```json
{
  "urls": [
    "https://site1.com",
    "https://site2.com",
    "https://site3.com"
  ],
  "selectors": ["h1", "p"],
  "options": {
    "delay": 2000
  }
}
```

### 5. 保存为 CSV

```bash
web-scraper scrape https://example.com -s "a" -a "href" \
  -o results.csv --format csv
```

## 💡 高级功能

### 代理支持

使用代理抓取：

```bash
web-scraper scrape https://example.com -p "http://127.0.0.1:8080"
```

测试代理连接：

```bash
web-scraper test-proxy "http://127.0.0.1:8080"
```

### User-Agent 轮换

自动轮换 User-Agent：

```bash
web-scraper scrape https://example.com --rotate-user-agent
```

### 数据转换

**类型转换：**

```bash
web-scraper transform data.json --rules '{"price":{"type":"number"},"text":{"maxLength":50}}'
```

**正则替换：**

```bash
web-scraper transform data.json --rules '{"price":{"regex":{"pattern":"\\$","replacement":""}}}'
```

**数据过滤：**

```bash
web-scraper transform data.json --filter '{"price":{"gte":100}}'
```

**去重：**

```bash
web-scraper transform data.json --dedup "title"
```

**数据聚合：**

```bash
web-scraper transform data.json --aggregate '{"price":"sum","count":"count"}'
```

### 自定义请求头

```bash
web-scraper scrape https://example.com \
  -H '{"User-Agent":"Mozilla/5.0"}'
```

```json
{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0",
    "Accept": "text/html"
  }
}
```

### 批量抓取配置

```json
{
  "urls": [
    "https://site1.com",
    "https://site2.com"
  ],
  "selectors": ["h1", "p"],
  "attributes": ["href"],
  "options": {
    "delay": 2000,
    "timeout": 60000,
    "saveHtml": false
  }
}
```

### 输出格式

#### JSON

```json
[
  {
    "selector": "h1",
    "index": 1,
    "text": "Example Title",
    "html": "<h1>Example Title</h1>"
  }
]
```

#### CSV

```csv
selector,index,text,href
h1,1,Example Title,https://example.com
a,1,Link 1,https://example.com/page1
```

## 📊 输出示例

```
🌐 抓取: https://example.com

📊 找到 5 个元素:

[1] h1
  Example Domain

[2] p
  This domain is for use in illustrative examples...

[3] a
  More information...
  属性: href="https://www.iana.org/domains/example"

[4] a
  Example link 1
  属性: href="/page1"

[5] a
  Example link 2
  属性: href="/page2"
```

## ⚠️ 注意事项

### 1. 遵守 robots.txt

检查网站的 robots.txt 文件，遵守抓取规则。

### 2. 控制频率

使用 `delay` 选项避免请求过快。

```bash
web-scraper run  # 配置 delay: 2000
```

### 3. 使用 User-Agent

有些网站会拒绝爬虫请求，设置 User-Agent。

```bash
web-scraper scrape https://example.com \
  -H '{"User-Agent":"Mozilla/5.0"}'
```

### 4. 法律合规

抓取前确保符合网站的使用条款和相关法律法规。

## 🔧 常见问题

### 抓取失败

检查：
- URL 是否正确
- 网站是否可访问
- 是否需要设置请求头
- 是否超时（增加 timeout）

### 没有结果

检查：
- CSS 选择器是否正确
- 页面是否是动态加载的（此工具不支持 JavaScript）
- 元素是否存在

### 被封禁

- 使用 delay 增加延迟
- 设置 User-Agent
- 更换 IP（如使用代理）

## 🚧 待实现

- [ ] 支持动态页面（Puppeteer/Playwright）
- [ ] 支持表单提交
- [ ] 支持登录认证
- [ ] 支持代理
- [ ] 支持增量抓取
- [ ] 导出更多格式（Excel、SQL）

## 🤝 贡献

欢迎提交 Issue 和 PR！

## 📄 许可证

MIT © 梦心

---

Made with 🌙 by 梦心