web-scraper

网页抓取工具

获取网页内容（文本 + 图片），并在本地保存为 HTML 或 Markdown。

依赖极少：仅需 requests 和 beautifulsoup4，无需浏览器自动化。

默认行为：自动将图片下载到本地 images/ 目录。

快速开始

单页

{baseDir}/scripts/scrape.py --url "https://example.com" --format html --output /tmp/page.html
{baseDir}/scripts/scrape.py --url "https://example.com" --format md --output /tmp/page.md

递归（跟随链接）

{baseDir}/scripts/scrape.py --url "https://docs.example.com" --format md --recursive --max-depth 2 --output ~/Downloads/docs-archive

设置

需要 Python 3.8+ 和极少的依赖：

cd {baseDir}
pip install -r requirements.txt

或手动安装：

pip install requests beautifulsoup4

注意：无需浏览器或驱动程序，使用纯 HTTP 请求。

需要收集的输入

单页模式

• URL：要抓取的网页（必填）
• 格式：html 或 md（默认：html）
• 输出路径：文件的保存位置（默认：当前目录，文件名自动生成）
• 图片：默认下载图片（使用 --no-download-images 禁用）

递归模式（--recursive）

• URL：递归抓取的起始地址
• 格式：html 或 md
• 输出目录：所有抓取页面的保存位置
• 最大深度：跟随链接的层级数（默认：2）
• 最大页面数：要抓取的页面总数上限（默认：50）
• 域名过滤：是否限制在同一域名内（默认：是）
• 图片：默认下载图片

对话流程

1. 询问用户要抓取的 URL
2. 询问首选输出格式（HTML 或 Markdown）
   • 注意：两种格式默认都包含文本和图片
   • HTML：保留原始结构，并下载图片
   • Markdown：清晰的文本格式，图片下载到 images/ 文件夹
3. 若使用递归模式：询问最大深度和最大页面数（可选，有合理的默认值）
4. 询问保存位置（或建议默认路径，例如 /tmp/ 或 ~/Downloads/）
5. 运行脚本并确认成功
6. 显示已保存的文件或目录路径

示例

单页抓取

保存为 HTML

{baseDir}/scripts/scrape.py --url "https://docs.openclaw.ai/start/quickstart" --format html --output ~/Downloads/openclaw-quickstart.html

保存为 Markdown（包含图片，默认）

{baseDir}/scripts/scrape.py --url "https://en.wikipedia.org/wiki/Web_scraping" --format md --output ~/Documents/web-scraping.md

结果：创建 web-scraping.md 和 images/ 文件夹，其中包含所有已下载的图片（文本 + 图片）。

不下载图片（可选）

{baseDir}/scripts/scrape.py --url "https://example.com" --format md --no-download-images

结果：仅包含文本和图片 URL（不下载到本地）。

自动生成文件名

{baseDir}/scripts/scrape.py --url "https://example.com" --format html
# Saves to: example-com-{timestamp}.html

递归抓取

基本递归爬取（深度 2、同一域名、包含图片）

{baseDir}/scripts/scrape.py --url "https://docs.example.com" --format md --recursive --output ~/Downloads/docs-archive

输出结构（所有页面均包含文本和图片）：

docs-archive/
├── index.md
├── getting-started.md
├── api/
│   ├── authentication.md
│   └── endpoints.md
└── images/              # Shared images from all pages
    ├── logo.png
    └── diagram.svg

使用自定义限制进行深度爬取

{baseDir}/scripts/scrape.py \
  --url "https://blog.example.com" \
  --format html \
  --recursive \
  --max-depth 3 \
  --max-pages 100 \
  --output ~/Archives/blog-backup

忽略 robots.txt（谨慎使用）

{baseDir}/scripts/scrape.py \
  --url "https://example.com" \
  --format md \
  --recursive \
  --no-respect-robots \
  --rate-limit 1.0

加快抓取速度（降低速率限制）

{baseDir}/scripts/scrape.py \
  --url "https://yoursite.com" \
  --format md \
  --recursive \
  --rate-limit 0.2

功能

单页模式

• HTML 输出：保留原始页面结构
  • ✅ 清晰易读的 HTML 文档
  • ✅ 所有图片均下载到 images/ 文件夹
  • ✅ 适合离线查看
• Markdown 输出：提取清晰的文本内容
  • ✅ 自动将图片下载到本地 images/ 目录（默认）
  • ✅ 将图片 URL 转换为相对路径
  • ✅ 格式清晰易读，适合归档
  • ✅ 下载失败时回退到原始 URL
  • 使用 --no-download-images 标志仅保留原始 URL
• 简单快速：纯 HTTP 请求，无需浏览器
• 自动文件名：未指定文件名时，根据 URL 生成安全的文件名

递归模式（--recursive）

• ✅ 智能发现链接：自动跟踪已爬取页面上的所有链接
• ✅ 深度控制：--max-depth 限制爬取的层级（默认值：2）
• ✅ 页面数量限制：--max-pages 限制页面总数，防止爬取失控（默认值：50）
• ✅ 域名筛选：--same-domain 将爬取范围限制在起始域名内（默认开启）
• ✅ 遵守 robots.txt：默认遵守网站的爬取规则
• ✅ 速率限制：--rate-limit 设置请求间隔（默认值：0.5s）
• ✅ 智能 URL 筛选：跳过图片、脚本、CSS 和重复 URL
• ✅ 进度跟踪：在控制台实时显示成功、失败和跳过的数量
• ✅ 有序输出：在目录层级中保留 URL 结构
• ✅ 高效爬取：按顺序爬取并限制速率，以尊重服务端

防护措施

单页模式

• 遵守 robots.txt 和网站服务条款
• 某些网站可能会阻止自动访问；此工具使用标准 HTTP 请求
• 含有大量图片的大型页面可能需要较长时间才能下载

递归模式

• 从小规模开始：先使用 --max-depth 1 --max-pages 10 进行测试
• 遵守 robots.txt：默认开启；仅对自有网站使用 --no-respect-robots
• 速率限制：默认值 0.5s 较为礼貌；访问公共网站时不要低于 0.2s
• 相同域名：强烈建议启用 --same-domain
• 监控进度：留意较高的失败率（这可能表明访问受阻）
• 存储空间：递归爬取可能生成许多文件；请确保有足够的磁盘空间
• 法律：确保已获得爬取和归档目标网站的许可

故障排除

• 连接错误：检查互联网连接和 URL 是否有效
• 403/被阻止：某些网站会阻止爬虫；此工具使用逼真的 User-Agent 标头
• 超时：对于加载缓慢的页面，请增大 --timeout 参数（单位为秒）
• 图片下载失败：图片将回退到原始 URL
• 图片缺失：某些网站使用 JavaScript 动态加载图片（暂不支持）