SiteOne 爬虫

跨平台网站爬取与分析工具，使用 Rust 编写。

设置（仅需执行一次）

首次使用前，请确保二进制文件已存在。若未找到，将自动安装：

1. 按以下优先级检查二进制文件是否存在：

- $HOME/.siteone-crawler/siteone-crawler

- $PATH 中的任意 siteone-crawler（通过 which siteone-crawler 查找）

1. 若以上均不存在，则从 GitHub 下载最新版本：

INSTALL_DIR="$HOME/.siteone-crawler"
mkdir -p "$INSTALL_DIR"
# 检测操作系统和架构
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in
  x86_64) ARCH="x64" ;;
  aarch64|arm64) ARCH="arm64" ;;
esac
# 通过 GitHub API 获取最新发布版本的下载链接
RELEASE_URL=$(curl -sL https://api.github.com/repos/janreges/siteone-crawler/releases/latest \
  | grep -oP "browser_download_url.*?${OS}-${ARCH}\.zip" | head -1 | sed 's/browser_download_url": "//')
curl -sL "$RELEASE_URL" -o /tmp/siteone-crawler.zip \
  && unzip -o /tmp/siteone-crawler.zip -d /tmp/siteone-crawler \
  && mv /tmp/siteone-crawler/siteone-crawler "$INSTALL_DIR/" \
  && chmod +x "$INSTALL_DIR/siteone-crawler" \
  && rm -rf /tmp/siteone-crawler /tmp/siteone-crawler.zip

1. 安装完成后，设置 CRAWLER 为解析后的路径，并通过 $CRAWLER --version 验证。

二进制文件路径

CRAWLER="$HOME/.siteone-crawler/siteone-crawler"

如果上述路径不存在，运行设置后可回退至 $(which siteone-crawler)。

始终使用解析后的路径。该二进制文件会向终端输出彩色文本；在脚本或流水线中使用时，请使用 --no-color，程序化消费时请使用 --output json。

常用工作流

1. 快速审计（生成 HTML 报告）

$CRAWLER --url="https://example.com" --output-html-report="/path/to/report.html"

生成一个自包含的交互式 HTML 审计报告，包含性能、SEO、安全、可访问性、最佳实践等维度的质量评分（0.0–10.0）。

2. 完整审计 + JSON 输出 + 上传

$CRAWLER --url="https://example.com" \
  --output-html-report="/path/to/report.html" \
  --output-json-file="/path/to/result.json" \
  --upload --upload-retention="7d"

3. 离线克隆

$CRAWLER --url="https://example.com" --offline-export-dir="/path/to/offline-site" --disable-javascript

对 SPA/React 类型站点，使用 --disable-javascript 可获取可浏览的静态副本。如需包含 CDN 资源，请配合使用 --allowed-domain-for-external-files="*"。

4. Markdown 导出

多文件导出（可浏览）：

$CRAWLER --url="https://example.com" --markdown-export-dir="/path/to/md-export"

单文件导出（适合 AI 工具处理）：

$CRAWLER --url="https://example.com" --markdown-export-dir="/tmp/md" --markdown-export-single-file="/path/to/site.md" \
  --markdown-disable-images --markdown-disable-files

5. 生成站点地图

$CRAWLER --url="https://example.com" --sitemap-xml-file="/path/to/sitemap" --sitemap-txt-file="/path/to/sitemap"

6. CI/CD 质量门禁

$CRAWLER --url="https://example.com" --ci --ci-min-score="7.0" --ci-max-404="0" --ci-max-5xx="0"

若未满足阈值，退出码为 10。所有 --ci-* 参数详见 references/cli-params.md。

7. 压力/负载测试

$CRAWLER --url="https://example.com" --workers="20" --max-reqs-per-sec="100" --max-depth="1"

警告：高并发数可能导致拒绝服务。请谨慎使用。

8. 单页爬取

$CRAWLER --url="https://example.com/about" --single-page --output-json-file="/path/to/result.json"

9. HTML 转 Markdown（本地文件）

$CRAWLER --html-to-markdown="/path/to/page.html" --html-to-markdown-output="/path/to/page.md"

10. 浏览导出内容

$CRAWLER --serve-markdown="/path/to/md-export" --serve-port="8321"
$CRAWLER --serve-offline="/path/to/offline-site" --serve-port="8321"

关键参数参考

详见 references/cli-params.md，按类别组织的完整参数说明。

最常用标志

资源过滤

URL 过滤

脚本辅助工具

scripts/audit.sh — 快速审计封装脚本

执行完整爬取并生成 HTML 报告，支持可选 JSON 输出。具体用法请查看脚本内容。

scripts/export-markdown.sh — Markdown 导出封装脚本

将网站导出为 Markdown（单文件或多文件）。具体用法请查看脚本内容。

使用建议

• 对现代 JS 框架（Next.js、React、Vue）站点进行离线导出时，建议添加 --disable-javascript
• 使用 --output json 以实现程序化处理；JSON 输出至 STDOUT，进度信息输出至 STDERR
• 使用 --extra-columns="Title,Keywords,Description" 添加 SEO 相关字段
• 使用 --timezone="Asia/Shanghai" 设置本地时间戳
• 对大型站点，可适当增加 --memory-limit、--max-visited-urls 和 --max-queue-length
• 使用 --resolve 可测试本地或开发环境服务器（类似 curl 的 --resolve 功能）
• HTML 报告为自包含文件，可在任意浏览器打开，无需服务器支持