ui-diff-tool 是一个面向前端视觉还原、页面验收和 UI 回归测试的开源命令行工具。它的核心思路很直接：把设计稿、网页截图或本地图片放到同一个对比流程里，用像素级差异图和 HTML 报告把“哪里不像设计稿”说清楚，再生成适合交给 AI 助手分析的修复提示。
项目概览
这个项目的仓库地址是 github.com/outhsics/ui-diff-tool。从项目说明看，它不是单纯的截图工具，而是把“截图、对齐、对比、报告、AI 修复提示”组合成一个完整的 UI 差异分析工作流。
| 项目定位 | 前端质量保障工具，用于设计稿到实现页面的视觉一致性校验 |
|---|---|
| 核心技术 | Node.js CLI、Playwright、pixelmatch、HTML 报告生成 |
| 主要输入 | 蓝湖设计稿、本地图片、远程图片、网页地址或页面截图 |
| 主要输出 | 差异图、实际截图、设计稿对齐图、HTML 报告、AI 修复提示文件 |
| 许可证 | MIT |
为什么这个项目值得关注？
前端页面验收最容易陷入“主观沟通”：设计说间距不对，开发说看着差不多，测试又很难把每个像素差异说清楚。ui-diff-tool 的价值就在于把这类沟通变成可视化证据：哪里偏移、哪里颜色不一致、哪里尺寸不对，都可以通过差异图和报告集中呈现。
- 对设计还原更友好：设计稿和实现页面可以直接做像素级对比，减少纯人工肉眼检查。
- 对移动端页面更实用：项目内置 iPhone、Pixel、Samsung 等常见设备预设，适合 H5、小程序、移动 Web 等页面验收。
- 对团队协作更清晰：HTML 报告比“截图圈红”更容易沉淀，也方便在评审、提测、返工时传递。
- 对 AI 辅助开发更顺手：生成的 AI 修复提示可以和差异图一起交给 Claude、GPT、Cursor 等工具分析，缩短定位问题的时间。
核心功能拆解
1. 像素级 UI 对比
项目使用 pixelmatch 进行图片差异比较，适合发现按钮位置、卡片尺寸、文本间距、颜色偏差等视觉问题。对于严格还原设计稿的页面，这比单纯截图留档更有指导意义。
2. Playwright 自动截图
当实际页面是一个 URL 时，工具可以通过 Playwright 打开页面并截图。你可以设置视口、设备预设、等待时间、选择器截图或整页截图，用于应对不同页面结构。
3. 多页面批量对比
除了单页对比，项目也支持通过配置文件批量跑多个页面。这对产品页、活动页、小程序页面或多端落地页尤其有用：一次配置，多页统一输出结果。
4. AI 可读修复提示
它不仅输出差异图片，还会生成面向 AI 的提示文件。这个设计很适合现在的前端工作流：开发者可以把差异图和提示一起交给 AI，让 AI 帮忙分析可能的 CSS、布局、字号、间距问题，再由开发者复核和提交。
快速上手
项目是 Node.js 命令行工具，运行环境要求 Node.js 16 或更高版本。首次使用时需要安装依赖，并安装 Playwright 的 Chromium 浏览器。
npm install
npx playwright install chromium最常见的单页对比方式，是把设计稿图片和实际页面 URL 传给 compare 命令：
npx ui-diff compare -d ./design.png -a http://localhost:3000/page如果实际页面已经被保存成截图，也可以直接对比两张本地图片：
npx ui-diff compare -d ./design.png -a ./screenshot.png移动端页面可以指定设备预设，例如 iPhone 14 Pro：
npx ui-diff compare -d ./design.png -a http://localhost:3000 --device iphone-14-pro --output ./ui-diff-output批量对比：更适合团队验收
如果一个版本里有多个页面要验收，可以先初始化配置，再把页面列表写进配置文件：
npx ui-diff init
npx ui-diff batch -c ./ui-diff.config.js配置文件可以维护输出目录、阈值、基础地址和页面列表。下面是一个简化示例：
module.exports = {
outputDir: './ui-diff-output',
threshold: 0.1,
viewport: 'iphone-12',
baseUrl: 'http://localhost:3000',
pages: [
{ name: '首页', design: './designs/home.png', actual: '/' },
{ name: '列表页', design: './designs/list.png', actual: '/list' }
]
};输出文件怎么用？
一次对比完成后，通常会得到以下几类结果：
- design.png：经过处理后的设计稿图。
- actual.png：实际页面截图。
- diff.png：差异标注图，适合快速定位问题区域。
- report.html：可视化报告，适合发给设计、测试和前端同学共同查看。
- ai-fix-prompt.md：面向 AI 助手的修复提示，可配合差异图分析问题。
- summary.html：批量模式下的汇总报告。
适合哪些使用场景？
| 场景 | 推荐理由 |
|---|---|
| H5 活动页验收 | 活动页视觉要求高，适合用差异图快速发现还原问题。 |
| 小程序页面还原 | 移动端预设可以降低视口配置成本。 |
| 设计走查 | 把反馈从“感觉不对”变成具体差异区域。 |
| 版本回归测试 | 改版后可以复跑关键页面，检查是否出现明显视觉偏差。 |
| AI 辅助修复 | 差异图 + 提示词能帮助 AI 更快理解问题上下文。 |
使用建议与注意点
- 保持截图环境稳定：字体、设备像素比、页面宽度、浏览器版本都可能影响视觉结果。
- 动态内容要做忽略处理：时间、头像、广告位、随机推荐等区域建议设置忽略，避免误报。
- 阈值不要盲目调得太低：严格对比适合组件验收，业务页面则可以适当放宽，重点关注明显差异。
- AI 建议需要人工复核：AI 可以辅助定位和生成修复思路，但最终代码仍应由开发者确认。
总结
ui-diff-tool 的亮点不只是“能截图对比”，而是把前端视觉验收做成了一条闭环：输入设计稿和页面，输出差异图与报告，再把修复提示交给 AI 辅助分析。对于重视设计还原的前端团队、移动端 H5 项目、小程序页面以及需要批量验收的业务页面，它都是一个值得收藏和尝试的项目。
项目地址：https://github.com/outhsics/ui-diff-tool
资料来源：项目 GitHub 仓库 README、package.json 与仓库页面。
评论