evolvingweb/sitediff

SiteDiff CLI**警告：SiteDiff 1.2.0 至少需要 Ruby 3.1.2。 警告：**SiteDiff 1.0.0 引入了一些不向后兼容的更改。

![构建状态]([***]

目录

• 概述与主要用途
• 核心功能与特性
• 使用场景与适用范围
• 使用方法与配置说明
  • 安装
  • 快速演示
  • 基本使用流程
  • 命令行选项
  • 配置详解
• Docker部署示例
• 提示与技巧

概述与主要用途

SiteDiff 可轻松查看网站的变化情况。它既能比较两个相似的网站，也能展示单个网站随时间的变化。该工具有助于识别网站HTML中不合需要的更改，是进行重新部署、网站升级等场景QA工作的实用工具。

运行 SiteDiff 后，会生成一份HTML报告，显示网站页面是否发生变化。对于已更改的页面，可查看彩色差异对比以了解具体变化，或在浏览器中并排比较视觉差异。SiteDiff 支持一系列标准化/清理规则，可消除虚假差异，将差异范围缩小到真正影响网站的部分。

核心功能与特性

• 网站对比：支持两个网站间对比或单个网站不同时间版本对比
• HTML报告生成：生成直观的HTML报告，清晰展示页面变化状态
• 差异可视化：提供彩色代码差异对比和并排视觉对比
• 灵活的标准化规则：通过DOM转换和正则表达式替换消除虚假差异
• 网站爬取：自动爬取网站以发现页面路径
• 配置自定义：通过YAML配置文件定制对比规则、选择器、报告信息等
• 多场景支持：支持本地文件系统路径对比、容器内运行等场景

使用场景与适用范围

• 网站重新部署后的质量验证
• 网站升级或迁移前后的一致性检查
• 生产环境与开发/测试环境的对比
• 跟踪网站内容随时间的变化
• CMS系统升级后的页面布局验证
• 检测因代码变更导致的意外HTML修改

使用方法与配置说明

安装

SiteDiff 安装相对简单。请参考 安装文档 获取详细步骤。

快速演示

安装包括 bundle 版本 2 gem 在内的所有依赖后，可通过以下命令快速体验 SiteDiff 的功能：

sh
git clone https://github.com/evolvingweb/sitediff
cd sitediff
bundle install
bundle exec thor fixture:serve

然后访问 http://localhost:13080/ 查看报告。报告将显示所有页面的概述，并清晰标记已更改和未更改的页面。点击已更改的页面，可查看页面标记的彩色差异对比。

基本使用流程

查看帮助

查看 SiteDiff 提供的命令列表： sitediff help

查看特定命令的帮助（如 diff）： sitediff help diff

入门使用

1. 创建配置：为网站创建配置 sitediff init http://mysite.example.com 默认生成名为 sitediff.yaml 的配置文件。

2. 爬取网站：让 SiteDiff 爬取网站以发现页面 sitediff crawl 爬取结果将保存到 paths.txt 文件。

3. 比较差异：在网站更改后检查变化 sitediff diff

4. 查看HTML报告：启动内部Web服务器查看报告 sitediff serve

5. 更新缓存：满意网站状态后更新缓存版本 sitediff store

比较两个网站

对比生产环境与开发环境网站： sitediff init http://mysite.example.com http://localhost/mysite

若两个网站都可能变化，禁用缓存： sitediff diff --cached=none

命令行选项

指定配置目录

默认 SiteDiff 将所有文件放在 sitediff 文件夹，可使用 --directory 标志指定其他目录：

bash
sitediff init -C my_project_folder https://example.com
sitediff diff -C my_project_folder
sitediff serve -C my_project_folder

指定页面路径

运行 sitediff diff 时，可通过以下方式指定要检查的页面：

1. 使用 --paths 选项：

   bash
   sitediff diff --paths /home /about /contact
   

2. 使用 --paths-file 选项指定路径文件：

   bash
   sitediff diff --paths-file sitediff/failures.txt
   

调试规则

调试清理规则时，使用 --cached=all 选项避免重新获取内容，加快比较速度：

bash
sitediff diff --cached=all

包含与排除URL

使用正则表达式包含或排除特定路径：

bash
# 排除PDF文件
sitediff crawl --exclude='.*\.pdf'

导出报告

生成包含HTML报告的压缩tar文件：

bash
sitediff diff --export
sitediff diff -e

容器内运行

在容器或虚拟机内运行时，可使用 --before-url-report 和 --after-url-report 选项调整报告中的URL：

bash
sitediff diff --after-url-report=http://vagrant:8080

配置详解

SiteDiff 依赖 YAML 配置文件（通常为 sitediff.yaml），可通过 sitediff init 生成基础配置，然后手动修改。

before_url / after_url

指定要比较的两个网站URL，也可以是本地文件系统路径：

yaml
before_url: http://example.com/subsite
after_url: http://localhost:8080/subsite

selector

指定要比较的HTML部分，而非整个页面：

yaml
selector: '#breadcrumb'  # 仅比较ID为breadcrumb的元素

sanitization

用于规范化HTML的正则表达式规则列表：

yaml
sanitization:
  # 移除Drupal表单构建ID
  - pattern: '<input type="hidden" name="form_build_id" value="form-[a-zA-Z0-9_-]+" *\/?>'
    selector: 'input'
    substitute: '<input type="hidden" name="form_build_id" value="__form_build_id__">'

ignore_whitespace

比较时忽略空白字符：

yaml
ignore_whitespace: true

命令行选项：-w 或 --ignore-whitespace

before / after

为比较的某一侧应用特定规则：

yaml
before:
  sanitization:
    - pattern: '[1-2][0-9]{3}/[0-1][0-9]/[0-9]{2}'
      substitute: '__date__'
after:
  sanitization:
    - pattern:  '[A-Z][a-z]{2} [0-9]{1,2}(st|nd|rd|th) [1-2][0-9]{3}'
      substitute: '__date__'

includes

包含其他配置文件：

yaml
includes:
  - config/sanitize_domains.yaml
  - config/strip_css_js.yaml

dom_transform

对HTML结构应用转换的规则列表，支持以下类型：

• remove：移除匹配选择器的元素

  yaml
  dom_transform:
    - type: remove
      selector: div#block-time  # 移除时间块
  

• strip：去除标签内容的前后空白

  yaml
  dom_transform:
    - type: strip
      selector: h1  # 去除h1标签内容的前后空白
  

• unwrap：用子元素替换匹配的元素

  yaml
  dom_transform:
    - type: unwrap
      selector: article  # 移除article标签，保留其内容
  

• remove_class：从元素中移除指定类

  yaml
  dom_transform:
    - type: remove_class
      selector: div
      class: class-foo  # 移除div元素的class-foo类
  

• unwrap_root：用子元素替换整个根元素

report

配置报告显示信息：

yaml
report:
  title: "example.com更新报告"
  details: "本报告验证example.com的更新情况。"
  before_note: "旧网站"
  after_note: "新网站"
  before_url_report: http://example.com
  after_url_report: http://staging.example.com

命名区域（Named regions）

定义页面标记中的区域及比较顺序，适用于标记结构变化较大的场景：

yaml
regions:
  - name: title
    selector: h1.title
  - name: author
    selector: .field-name-attribution
  - name: body
    selector: .field-name-body
output:
  - title
  - author
  - body

Curl选项

配置底层curl库的选项：

yaml
settings:
  curl_opts:
    max_recv_speed_large: 10000  # 限制接收速度
    ssl_verifypeer: false        # 忽略SSL证书验证
    timeout: 60                  # 超时时间（秒）
    concurrency: 3               # 最大并发连接数
    interval: 1000               # 请求间隔（毫秒）
    depth: 3                     # 爬取深度

Docker部署示例

使用docker run命令

bash
# 初始化配置
docker run -v $(pwd)/sitediff:/app/sitediff sitediff/sitediff init http://old.example.com http://new.example.com

# 爬取网站路径
docker run -v $(pwd)/sitediff:/app/sitediff sitediff/sitediff crawl

# 生成差异报告
docker run -v $(pwd)/sitediff:/app/sitediff sitediff/sitediff diff

# 启动报告服务器（访问http://localhost:13080查看报告）
docker run -v $(pwd)/sitediff:/app/sitediff -p 13080:13080 sitediff/sitediff serve

docker-compose配置示例

yaml
version: '3'
services:
  sitediff:
    image: sitediff/sitediff
    volumes:
      - ./sitediff:/app/sitediff  # 挂载配置和数据目录
    ports:
      - "13080:13080"  # 映射报告服务器端口
    command: serve  # 启动报告服务器

提示与技巧

移除空元素

yaml
sanitization:
  - name: remove_empty_p
    pattern: '<p/>'
    substitute: ''  # 移除空的<p/>标签

HTML标签格式化

yaml
sanitization:
  - name: remove_space_before
    pattern: '\s*(\n)<'
    substitute: '\1<'  # 移除标签前的空格

  - name: remove_space_after
    pattern: '>(\n)\s*'
    substitute: '>\1'  # 移除标签后的空格

处理空属性

yaml
sanitization:
  - name: remove_empty_class
    pattern: ' class=""'
    substitute: ''  # 移除空的class属性

配置文件组织

将大型配置文件拆分为多个文件：

yaml
includes:
  - generic_rules.yaml  # 通用规则
  - update_specific_rules.yaml  # 特定更新规则

选择器使用建议

• 对选择器使用单引号或双引号，注意YAML中#是注释符号
• 选择器应足够具体，避免影响其他页面的元素