renderlint - 在真实浏览器里给渲染后的界面做视觉缺陷检查

renderlint 是一个针对「渲染后的界面」的检查工具。据项目自述，它会在真实浏览器里打开你的应用，找出编码代理交付的视觉缺陷，并在缺陷未修复时让构建失败。它要解决的问题很具体：TypeScript 和 ESLint 看不到这类问题，因为代码本身是「对的」，错的是像素——文字溢出卡片、灰底灰字、图表标签互相压叠、只在 1024px 宽度才崩的布局、下拉箭头贴着边框、KPI 卡片里显示 $undefined、该用图标的地方放了 emoji。它适合使用编码代理（如 Claude Code、Cursor、Codex 等）批量产出界面的团队，也适合任何希望在 CI 中加一道 UI 质量闸门的 Web 项目。

维护者与状态

项目由 ngocanhnckh 维护，仓库创建于 2026-10-25，最后提交时间为 2026-11-13。截至 2026-11-15，仓库星标数为 507。事实表显示该项目尚无正式 release；不过素材中的 README 提到了 0.2.0 版本的新增内容，这属于项目自述，读者可自行到仓库核对实际发布状态。

主要能力

以下内容据项目 README 自述整理，未经独立验证：

• 多视口渲染与扫描：在手机、平板、桌面宽度以及深色模式下渲染每个页面，并扫描中间宽度；再用更长的文本、更大的数字和更长的 API 数据重新检查一遍。
• 规则集：README 称共有 52 条规则，覆盖文字溢出与裁切（text-overflow、text-clipped、text-crowding）、脆弱布局（fragile-layout）、对比度（contrast，从真实像素测量，因此对渐变与图片背景也有效）、元素重叠与视口溢出、SVG 图表标签碰撞、无法滚动到的内容（unreachable-content）、被遮挡内容、被 z-index 或 overflow: hidden 困住的菜单（popup-obscured）、emoji 代替图标、undefined/NaN/[object Object] 等占位文本、图片破损与拉伸、控件高度不一致，以及浏览器原生 alert()/confirm() 弹窗（native-dialog）。
• 加载状态检查：README 称会放慢页面 API 请求，标记等待期间一直空白、没有 spinner 或骨架屏的区域，以及数据到达时发生跳动的内容。
• UX 深度检查（--ux）：模拟用户点击各类按钮、标签页、链接、筛选下拉与表单（用测试数据填写），报告一秒内无响应的点击、无人告知的失败（以 HTTP 500 应答请求）、重复提交的表单、无反应的按钮与超过 500ms 的卡顿；据项目说明，写操作不会到达服务器。
• 空列表、对话框与返回键：以全新账号视角加载页面，标记空白列表、永不停止的 spinner 与崩溃页面；检查对话框是否接管焦点、能否用 Escape 关闭并归还焦点，以及应用内跳转后返回键是否真的返回。
• 路由与角色覆盖：从源码（Next.js、Nuxt、SvelteKit、Astro、React Router / Remix、TanStack Router、Angular、Vue Router）和运行中的路由器读取路由，动态路由如 /products/:id 用真实 id 填充；配置 roles 后可按管理员、访客等角色同时检查每个页面，并给出覆盖率报告。
• 登录后的页面：可设置路由守卫读取的 token 并 mock API，或通过真实表单登录；服务端渲染应用在服务端同样获得 mock，使 middleware.ts 与 loader 得以执行。只显示登录表单或「拒绝访问」的页面会被报告，而不会被判为通过。
• 与测试工具集成：withRenderlint(test) 可检查 e2e 测试到达的每个状态，renderlint storybook 可检查每个 story。
• 面向编码代理：init 会安装三个 Claude Code skill，分别用于配置页面与角色、修复发现的问题、以及 Playwright 与 Storybook 集成。

每条缺陷报告包含元素、源文件位置、标注过的截图和一条具体的修复建议，以纯文本形式输出，便于代理直接执行。

使用入口

仓库地址：ngocanhnckh/renderlint。

据 README，一次性初始化与检查命令如下：

npx -y @yitec/renderlint init
npx renderlint

也可以作为开发依赖安装：

npm i -D @yitec/renderlint

不安装、只试一次时可传入地址：

npx -y @yitec/renderlint http://localhost:3000

README 还给出了一种用法：把初始化指令粘贴给编码代理，由代理执行 init 并遵循它写入 AGENTS.md 的「UI quality gate: renderlint」一节，在每次 UI 改动后运行检查，直到错误数为 0。检查命令在发现错误时以退出码 1 结束，因此可直接作为构建闸门。

许可与限制

项目采用 MIT 许可证。

关于适用边界，README 中列有「Limitations」一节，但本次素材未包含其具体内容，因此这里不做推断。从素材可确认的前置条件包括：需要能在真实浏览器中运行应用（依赖 Playwright 相关能力），需要为登录后的页面配置 token 或 mock，服务端渲染场景需要在服务端提供 mock。项目自述的规则经过调校，目标是「发现的问题几乎总是真实缺陷」，但这属于维护者的自我评价，实际误报率需使用者自行评估。此外，项目尚无正式 release，接口与配置方式可能随提交变化，接入生产流程前建议锁定版本。