CauseScope：点击 React 界面，追到源码、状态与网络响应

一个退款按钮为什么是灰的？代码里最先看到的往往只有这一行：

tsx
<button disabled={!canRefund}>Refund order</button>

disabled 不是答案，只是症状。接下来还要找 canRefund 从哪里来、哪次状态更新改变了订单、这个状态是否来自接口，以及页面上看到的值对应哪一个组件实例。项目一大，搜索变量名很快就会变成跨组件、跨文件、跨运行时的侦查。

我做了 CauseScope，想把这段路径压缩成一次从页面开始的检查：点击真实 UI，沿着已经观察到的证据回到源码、条件、状态与网络响应。

可以直接打开 StackBlitz 在线实验室体验，不需要先改自己的项目。源码、问题与讨论都在 GitHub，安装包发布在 npm。

CauseScope 是什么？

**CauseScope 是一个面向 React + Vite 开发环境的本地证据检查器。**它允许开发者从页面上的任意元素出发，查看精确 TSX 位置、当前表达式与条件分支、相关状态更新，以及能够确认关联的 Fetch/XHR 响应。没有被观察到或无法可靠关联的证据，会明确显示为不可用，而不是补出一条看似合理的因果链。

这一区别很重要。调试工具如果把推测包装成事实，界面再漂亮也会把人带向错误文件。

真正难找的不是 `false`，而是它为什么变成 `false`

React DevTools 很适合查看组件树、Props 和 Hooks。浏览器 Network 面板也能完整展示请求。问题在于，这些证据通常分散在不同视图里，需要开发者自己建立关联。

退款示例里，CauseScope 展示的不是一句 “canRefund = false”，而是一条可核对的路径：

text
<button disabled={!canRefund}>Refund order</button>
                     │
                     ├─ canRefund → false
                     ├─ order.status === "paid" → false
                     ├─ order.status = "pending"
                     └─ GET /api/orders/4821 · 200

这里的价值不是替代源码阅读，而是先把阅读起点放准。开发者可以立即看到：渲染结果来自哪个表达式，阻断分支是什么，最近一次真实 setter 或 reducer 更新在哪里发生，以及响应中的哪个字段与当前值有关。

`disabled` 只是一种场景，不是产品模型

按钮置灰适合演示，因为因果关系足够直观；CauseScope 并没有把所有元素都套进 disabled 模板。

选择普通文本时，如果它没有动态决策，检查器只显示对应的源码片段、组件名以及文件、行、列。选择输入框、列表项或链接时，也只展示这个元素实际拥有的证据。缺少状态更新或网络来源，就不会出现一串 undefined 占位，更不会虚构 setter、请求或阻断分支。

当前检查器提供五类视图：

视图	能回答的问题
Why	这段 UI 来自哪段 TSX？表达式结果、操作数和条件树是什么？
Values	当前组件实例的 Props 与 Hook state 是什么？
State	初始值和最近一次真实 setter/reducer 更新发生在哪里？
Network	哪个 Fetch/XHR 响应及字段能被确认与当前值相关？
Timeline	DOM 事件、handler、状态更新、render 和表达式变化如何串联？

它还提供精确的文件、行、列坐标和编辑器无关的 “Open in editor”。抽屉打开后可以直接选择下一个页面元素，不需要先退出再重新进入检查模式。

它如何避免拼出一条“看起来像因果”的解释？

CauseScope 把证据采集拆在几个边界清晰的层里。开发服务器中的 Vite 插件先执行 Babel transform，为项目自己的 TSX 节点加入稳定的源码元数据，并包裹需要观察的表达式；转换需要保持原来的求值次数与短路行为，不能为了调试改变应用语义。

浏览器中的 core runtime 只记录有上限的事件和值，再尝试把它们与状态、DOM 事件、store、网络响应和 storage 访问关联。React Fiber 的读取被隔离在单独的 React 适配层中，分别兼容 React 18 与 19；检查抽屉则由 Preact 渲染在 Shadow DOM 内，避免应用 CSS 反过来污染工具界面。

这套分层并不能让所有来源都变得可知。它的作用是让“已确认”“有歧义”和“不可用”拥有不同的展示结果。生产验证还会扫描构建产物中的运行时与 instrumentation 标记，防止开发工具静默进入线上包。

如何在一分钟内接入 React + Vite？

当前版本支持 React 18/19 与 Vite 5–8，也覆盖 Babel 和 SWC 两条官方 React 插件路径。

安装开发依赖：

bash
npm i -D causescope@beta

在 vite.config.ts 中加入插件：

ts
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
import causeScope from "causescope/vite"

export default defineConfig({
  plugins: [react(), causeScope()],
})

启动原来的 Vite 开发服务器，点击 Inspect 后选择元素。也可以按住 Option / Alt 点击，直接开始检查。

React Query 与 Zustand 有显式适配器。它们必须由项目主动安装，CauseScope 不会扫描页面上无关的 store 来“猜”数据来源。

为什么坚持 local-first 和 development-only？

追踪 Props、状态与响应意味着工具有机会接触敏感开发数据，所以它的信任边界不能只写在宣传语里。

CauseScope 没有账号、遥测、云服务或上传入口。它只在 vite serve 的开发模式运行；生产构建中不应包含运行时、抽屉、编辑器端点或调试属性。网络与 storage 追踪可以分别关闭，默认记录也有数量和体积上限。

常见的 authorization、cookie、API key、token、password 与 secret 变体会在界面和导出中被脱敏。不过自动规则不可能理解每个业务里的私有字段，分享 trace 前仍应添加项目规则并人工检查。更完整的边界写在 Privacy and threat model 中。

当前边界：Vite-first，还不是 Next.js 工具

CauseScope 目前明确是 Vite-first。React 18/19 + Vite 5–8 是受支持范围，Next.js 尚未支持。

我已经把 Next.js 可行性结论写进 ROADMAP：Client Component 范围在技术上有可能成立，但 React Server Components 没有浏览器 DOM、客户端 Fiber 状态，也不包含服务端请求执行，这些都是现有证据模型不能跨过去假装连续的边界。

在精确源码位置、Turbopack 与 webpack 一致性、生产移除、RSC 诚实降级以及性能门槛都有公开 fixture 和自动化验证之前，项目不会写“支持 Next.js”。这会缩小当前受众，但比让使用者读到一半才发现限制更可信。

它适合解决什么问题？

CauseScope 最适合这样的时刻：UI 症状很具体，但原因散落在多个层级。

按钮为什么不可用，哪一个条件在阻断？
一段状态文案为什么没有切换到预期分支？
当前值来自 Props、本地 state、store，还是请求响应？
setter 被调用了，为什么这一个组件实例仍显示旧值？
一次点击之后，handler、状态更新和重新渲染的顺序是什么？

它不打算替代 React DevTools、Network 面板、性能分析器或源码调试器。它做的是它们之间经常缺失的那一步：从你正在看的 UI，给出一条可核对的证据路径。

我的判断

前端调试长期以“工具拥有什么数据”来组织界面：组件在一处，请求在一处，源码又在另一处。开发者遇到的却不是数据分类问题，而是一个更直接的问题——“为什么我眼前的东西是这样？”

CauseScope 试着把入口换成这个问题本身。它目前仍处于 beta，真正需要的不是抽象的点赞，而是不同项目结构下的反例：定位不准的组件、丢失的状态来源、无法确认的请求关联、影响交互的性能路径。

如果你在维护 React + Vite 项目，可以先用在线实验室判断它是否解决了真实问题，再决定是否安装。遇到问题时，欢迎提交经过脱敏的最小 TypeScript 复现；如果这个方向值得继续，也欢迎在 GitHub 给项目一个 Star。