285 lines
6.4 KiB
Markdown
285 lines
6.4 KiB
Markdown
# Browser Automation Skill
|
||
|
||
使用 Playwright 调用本地 Chrome 进行反检测浏览器自动化。
|
||
|
||
## 简介
|
||
|
||
此 Skill 封装了浏览器自动化功能，专门设计用于规避常见的爬虫检测机制（如 Cloudflare、DataDome 等）。通过使用本地安装的 Chrome 并配置反检测参数，可以模拟真实用户行为。
|
||
|
||
## 特点
|
||
|
||
- ✅ **反检测模式**：禁用 `navigator.webdriver` 标记，绕过自动化检测
|
||
- ✅ **本地 Chrome**：使用系统安装的 Google Chrome，而非 Playwright 自带的 Chromium
|
||
- ✅ **两种模式**：
|
||
- **launch 模式**：直接启动 Chrome（带反检测参数）
|
||
- **cdp 模式**：连接已运行的 Chrome 实例
|
||
- ✅ **简洁 API**：navigate, click, type, snapshot, scroll, screenshot, close
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
# 安装 Playwright
|
||
pip install playwright
|
||
|
||
# 安装 Chromium（playwright 需要，虽然我们使用本地 Chrome）
|
||
playwright install chromium
|
||
```
|
||
|
||
## 使用方式
|
||
|
||
### 1. 基础用法（Launch 模式）
|
||
|
||
```python
|
||
from browser_tool import BrowserTool
|
||
|
||
# 创建浏览器实例
|
||
browser = BrowserTool(mode="launch", headless=False)
|
||
|
||
# 导航到页面
|
||
snapshot = browser.navigate("https://example.com")
|
||
print(snapshot)
|
||
|
||
# 点击元素
|
||
browser.click("@e5")
|
||
|
||
# 输入文本
|
||
browser.type("@e3", "search query")
|
||
browser.press("Enter")
|
||
|
||
# 滚动页面
|
||
browser.scroll("down")
|
||
|
||
# 截图
|
||
path = browser.screenshot()
|
||
|
||
# 关闭
|
||
browser.close()
|
||
```
|
||
|
||
### 2. 使用上下文管理器
|
||
|
||
```python
|
||
from browser_tool import BrowserTool
|
||
|
||
with BrowserTool(mode="launch", headless=False) as browser:
|
||
snapshot = browser.navigate("https://example.com")
|
||
print(snapshot)
|
||
# 自动关闭
|
||
```
|
||
|
||
### 3. CDP 模式（连接已运行的 Chrome）
|
||
|
||
首先启动 Chrome 并开启调试端口：
|
||
|
||
```bash
|
||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
|
||
--remote-debugging-port=9222 \
|
||
--user-data-dir=/tmp/chrome_debug
|
||
```
|
||
|
||
然后在代码中连接：
|
||
|
||
```python
|
||
from browser_tool import BrowserTool
|
||
|
||
browser = BrowserTool(mode="cdp", cdp_url="http://localhost:9222")
|
||
snapshot = browser.navigate("https://example.com")
|
||
```
|
||
|
||
### 4. 使用快捷函数
|
||
|
||
```python
|
||
from browser_tool import create_browser
|
||
|
||
browser = create_browser(mode="launch", headless=False)
|
||
```
|
||
|
||
### 5. 启动 Chrome 调试实例
|
||
|
||
```python
|
||
from browser_tool import launch_chrome_debug_port
|
||
|
||
# 启动 Chrome 并开启 9222 端口
|
||
proc = launch_chrome_debug_port(port=9222)
|
||
|
||
# 之后可以用 CDP 模式连接
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### BrowserTool 类
|
||
|
||
#### 构造函数
|
||
|
||
```python
|
||
BrowserTool(
|
||
mode: Literal["launch", "cdp"] = "launch",
|
||
cdp_url: str = "http://localhost:9222",
|
||
headless: bool = False,
|
||
chrome_path: Optional[str] = None,
|
||
)
|
||
```
|
||
|
||
参数：
|
||
- `mode`: 启动模式，`"launch"` 直接启动 Chrome，`"cdp"` 连接已运行的 Chrome
|
||
- `cdp_url`: CDP 连接地址（仅 mode="cdp" 时使用）
|
||
- `headless`: 是否无头模式（建议 False 规避检测）
|
||
- `chrome_path`: Chrome 可执行文件路径（默认使用 `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`）
|
||
|
||
#### 方法
|
||
|
||
##### navigate(url, wait_until="networkidle") -> str
|
||
|
||
导航到指定 URL，返回页面快照。
|
||
|
||
- `url`: 目标网址
|
||
- `wait_until`: 等待条件 (`load`, `domcontentloaded`, `networkidle`)
|
||
|
||
返回：页面快照文本，包含交互元素列表
|
||
|
||
##### snapshot(full=False) -> str
|
||
|
||
获取当前页面快照。
|
||
|
||
- `full`: 是否返回完整页面内容（默认只返回交互元素）
|
||
|
||
##### click(ref, wait_for_navigation=False)
|
||
|
||
点击元素。
|
||
|
||
- `ref`: 元素引用 ID，如 `@e5`
|
||
- `wait_for_navigation`: 是否等待页面跳转
|
||
|
||
##### type(ref, text, clear=True)
|
||
|
||
在输入框填入文本。
|
||
|
||
- `ref`: 元素引用 ID
|
||
- `text`: 要输入的文本
|
||
- `clear`: 是否先清空输入框
|
||
|
||
##### scroll(direction="down", amount=500)
|
||
|
||
滚动页面。
|
||
|
||
- `direction`: `"up"` 或 `"down"`
|
||
- `amount`: 滚动像素数
|
||
|
||
##### screenshot(path=None) -> str
|
||
|
||
截取页面截图。
|
||
|
||
- `path`: 截图保存路径（默认自动命名）
|
||
|
||
返回：截图文件路径
|
||
|
||
##### press(key)
|
||
|
||
按下键盘按键。
|
||
|
||
- `key`: 按键名称 (`Enter`, `Tab`, `Escape`, `ArrowDown`, 等)
|
||
|
||
##### back()
|
||
|
||
返回上一页。
|
||
|
||
##### close()
|
||
|
||
关闭浏览器会话。
|
||
|
||
##### check_detection() -> Dict
|
||
|
||
检查反检测效果，访问 https://bot.sannysoft.com/ 并返回检测结果。
|
||
|
||
返回：包含 `webdriver`, `plugins`, `languages`, `userAgent`, `chrome` 等字段的字典
|
||
|
||
## 页面快照格式
|
||
|
||
`snapshot()` 和 `navigate()` 返回的快照文本格式如下：
|
||
|
||
```
|
||
URL: https://example.com
|
||
Title: Example Domain
|
||
|
||
=== Interactive Elements ===
|
||
|
||
[@e1] <a href="https://example.com/page">Link text</a>
|
||
[@e2] <button type="submit">Submit</button>
|
||
[@e3] <input type="text" placeholder="Search...">
|
||
[@e4] <textarea name="content">
|
||
```
|
||
|
||
使用 `@e1`, `@e2` 等引用 ID 进行点击和输入操作。
|
||
|
||
## 反检测原理
|
||
|
||
1. **使用本地 Chrome**：而非 Playwright 自带的 headless Chromium，避免被识别为自动化浏览器
|
||
2. **禁用 webdriver 标记**：通过 `Object.defineProperty` 将 `navigator.webdriver` 设为 `undefined`
|
||
3. **配置启动参数**：
|
||
- `--disable-blink-features=AutomationControlled`：禁用自动化控制特征
|
||
- `--disable-web-security`：禁用 web 安全（可选）
|
||
- `--window-size`：设置正常 viewport
|
||
4. **非无头模式**：`headless=False` 让 Chrome 真实显示
|
||
|
||
## 常见问题
|
||
|
||
### Q: Chrome 路径不对？
|
||
|
||
在创建 BrowserTool 时指定路径：
|
||
|
||
```python
|
||
browser = BrowserTool(chrome_path="/path/to/chrome")
|
||
```
|
||
|
||
### Q: 如何查找 Chrome 路径？
|
||
|
||
```bash
|
||
# macOS
|
||
ls /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
|
||
|
||
# 或使用 mdfind
|
||
mdfind -name "Google Chrome.app"
|
||
```
|
||
|
||
### Q: CDP 模式连接失败？
|
||
|
||
确保 Chrome 已启动并开启调试端口：
|
||
|
||
```bash
|
||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
|
||
--remote-debugging-port=9222
|
||
```
|
||
|
||
检查端口是否监听：
|
||
|
||
```bash
|
||
curl http://localhost:9222/json/version
|
||
```
|
||
|
||
### Q: 还是被检测到了？
|
||
|
||
尝试以下方法：
|
||
1. 确保 `headless=False`
|
||
2. 使用 CDP 模式连接手动启动的 Chrome
|
||
3. 添加更多延迟：`browser._page.wait_for_timeout(2000)`
|
||
4. 使用代理或 VPN 更换 IP
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
browser-automation/
|
||
├── SKILL.md # 本文档
|
||
└── browser_tool.py # 核心封装
|
||
```
|
||
|
||
## 依赖
|
||
|
||
- Python 3.8+
|
||
- Playwright
|
||
- Google Chrome（本地安装）
|
||
|
||
## 参考
|
||
|
||
- [Playwright Documentation](https://playwright.dev/python/)
|
||
- [bot.sannysoft.com](https://bot.sannysoft.com/) - 浏览器自动化检测测试
|