# @reneturcios/visualdiff 中文文档

规范地址：https://npmcn.com/package/%40reneturcios/visualdiff/

版本：0\.1\.0
npm 元数据更新时间：2026-11-02T06:37:21.265Z
中文译文更新时间：2026-11-02T08:34:11.145Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40reneturcios/visualdiff
原文对照：https://npmcn.com/package/%40reneturcios/visualdiff/?lang=original
项目主页：https://github.com/CloudCorpRecords/visualdiff#readme
源码仓库：https://github.com/CloudCorpRecords/visualdiff

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：49 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-11-02T06:35:13.550Z
- 最新版本发布：2026-11-02T06:37:21.105Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

来自终端和MCP的SnapDiff视觉测试：根据基线验证UI更改，比较页面，捕获屏幕截图，并将HTML/CSS呈现为图像。一个bin提供一个小型CLI和一个studio MCP服务器。

## 安装

```sh
npm install @reneturcios/visualdiff
```

也可以使用：`pnpm add @reneturcios/visualdiff`、`yarn add @reneturcios/visualdiff`、`bun add @reneturcios/visualdiff`

## README

# visualdiff

visualdiff包装了SnapDiff视觉测试API：验证一个UI 改变与你想要做的事情相匹配，区别两页（或一页） 根据存储的基线)，捕获任何URL的屏幕截图，以及 将原始HTML/CSS直接渲染为图像。一个二进制服务于 命令行接口和stdio MCP服务器。

需要API密钥。集 `SNAPDIFF_API_KEY` 一把钥匙从 SnapDiff仪表板;在发出任何请求之前调用失败 不见了。API基URL可以被覆盖 `SNAPDIFF_API_URL`;未设置时，呼叫转到 `https://api.snapdiff.ai/v1`.

## 安装

```bash
npx @reneturcios/visualdiff screenshot https://example.com
```

或者运行容器镜像：

```bash
docker run -i -e SNAPDIFF_API_KEY=sk_live_... ghcr.io/cloudcorprecords/visualdiff
```

容器默认为MCP服务器（见下文）。通过CLI 参数将其用作CLI。

## 命令行界面

```bash
export SNAPDIFF_API_KEY=sk_live_...

visualdiff verify myproj pricing https://staging.example.com/pricing "added a yearly billing toggle"
visualdiff compare https://staging.example.com --before https://www.example.com
visualdiff compare http://localhost:3000 --project myproj --page-name homepage
visualdiff screenshot https://example.com --width 800 --full-page
visualdiff html-to-image "<h1>Hello</h1>" --css "h1 { color: navy; }" --width 1200 --height 630

visualdiff --version
```

命令打印上游JSON负载。退出代码: `0` 在 成功, `1` 当调用失败时（包括丢失API密钥或错误） 上游API错误)， `2` 使用错误。

## MCP服务器

一个箱子能同时满足两个人的需要。这个 `mcp` subcommand启动stdio MCP 服务器:

```bash
npx -y @reneturcios/visualdiff mcp
```

MCP客户端配置：

```json
{
  "mcpServers": {
    "visualdiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/visualdiff", "mcp"],
      "env": { "SNAPDIFF_API_KEY": "sk_live_..." }
    }
  }
}
```

### 工具

| 工具 | 输入 | 它返回什么 |
| --- | --- | --- |
| `snapdiff_verify_ui_change` | `project`， `page_name`， `after`， `intent` (所有必需的);可选 `intent_regions`， `branch`， `threshold`， `match_tolerance_percent`， `ignore_selectors`， `full_page` | 判决(`pass`， `expected_change_detected`， `unexpected_regression`， `no_change_detected`，或者 `needs_human_review`),一个 `next_action`，和 `review_url`． 需要一个具有存储页面基线的项目。 |
| `snapdiff_compare_pages` | `after` (需要);+ `before`，或者 `project` + `page_name` 对于基线模式；可选 `branch`， `threshold`， `ignore_selectors`， `full_page` | 差值百分比加上高亮显示的差值图像。 |
| `snapdiff_capture_screenshot` | `url` (需要);可选 `full_page`， `dark_mode`， `selector`， `width` | 页面截图。 |
| `snapdiff_html_to_image` | `html` (需要);可选 `css`， `width`， `height` | 渲染的图像（OG卡、社交图像、电子邮件标题）。 |

每个工具作为POST发送到基础下的每个工具端点 使用API密钥作为承载令牌的URL。可选参数 请求体中完全省略了未提供的。

## 开发

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## 许可证

MIT -见 `LICENSE`.

## 常见问题

### @reneturcios/visualdiff 是什么？

来自终端和MCP的SnapDiff视觉测试：根据基线验证UI更改，比较页面，捕获屏幕截图，并将HTML/CSS呈现为图像。一个bin提供一个小型CLI和一个studio MCP服务器。

### 如何安装 @reneturcios/visualdiff？

在项目目录运行 npm install @reneturcios/visualdiff，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 visualdiff，可以用 npx visualdiff 直接运行。

### @reneturcios/visualdiff 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/reneturcios\_\_visualdiff 是否存在。

### @reneturcios/visualdiff 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @reneturcios/visualdiff 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @reneturcios/visualdiff 可以商用吗？

@reneturcios/visualdiff 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @reneturcios/visualdiff 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/02（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。