Foldkit DevTools完全指南:用时间旅行调试快速定位每一次状态变化

原创2026-10-17 19:09:302,246 阅读

Foldkit DevTools完全指南:用时间旅行调试快速定位每一次状态变化

Foldkit DevTools 是 Foldkit 框架内置的浏览器调试面板,通过时间旅行调试(Time-Travel)能力,让你像倒带视频一样回放到任意一次状态变化,快速定位"页面为什么变成这样"。它记录流经应用的每一条 Message,并保存对应的 Model 快照,无需打断点、无需 console.log,一次点击就能回到问题发生前的那一刻。

Foldkit DevTools 时间旅行调试面板:深色主题的 Message 时间线与 Model 检查器

一、Foldkit DevTools 是什么?

Foldkit 采用单一数据源架构:所有状态变化都必须经过 update 函数,以 Message 的形式流转。DevTools 正是利用了这一特性,成为框架的"黑匣子":

  • 完整时间线:列出每一条被记录的 Message,最新条目在底部
  • 四个检查器标签页:Model(完整状态树,高亮变化的路径)、Message(消息载荷)、Commands(本次更新返回的副作用)、Mounts(该次渲染中启动或结束的挂载)
  • 时间旅行:选中任意历史行,UI 会回放到那个历史 Model 的暂停视图;Resume 一键恢复最新实时视图,Clear 清空历史记录但不重启应用
  • 零样式污染:面板渲染在 shadow DOM 内,不会干扰你的样式和布局

面板源码位于 packages/devtools/src/overlay.ts,官方文档见 packages/website/src/page/core/devtools.md。

二、一键启用:开发环境自动挂载

启用 DevTools 只需要一条安装命令,@foldkit/vite-plugin 会在开发环境自动挂载面板,生产构建则自动剔除,无需手写环境判断:

pnpm add -D @foldkit/devtools

若需要配置位置等选项,在 makeApplication 中传入 devTools 对象即可(完整配置见 packages/devtools/README.md):

const application = Runtime.makeApplication({
  // ...
  devTools: {
    position: 'BottomLeft',
  },
})

配置示例源码可参考 devtoolsBasic.ts。

三、读懂状态时间线:3步复现任何 Bug

  1. 打开面板:找到页面右下角的 DevTools 标签页并展开
  2. 定位可疑 Message:在时间线中找到异常发生前的那一条,右侧会标注该条消息耗时
  3. 切换检查器:Model 页高亮出这条 Message 改动了哪些状态路径,Commands 页显示它触发了哪些副作用——问题原因一目了然

四、时间旅行模式 vs 检查模式

这是 DevTools 最核心的功能。两种模式各司其职(源码注释):

模式 行为 适用场景
TimeTravel(默认) 选中历史行即暂停并回放到该状态,实时应用照常运行,新消息仍会出现在面板中 本地开发调试,需要"钉住"某个状态反复研究
Inspect 只读浏览历史快照,不暂停应用 生产/预发环境,访客也能打开面板但不能"弄坏"页面

还可以按环境分别指定模式,本地可时间旅行、线上只读检查:

devTools: {
  show: 'Always',
  mode: { development: 'TimeTravel', production: 'Inspect' },
  banner: 'Welcome to our app! Browse the state tree to see how it works.',
}

该配置示例见 devtoolsInspect.ts。

Foldkit DevTools 浅色主题的 inspect 模式:浏览 Model 状态树而不暂停应用

五、高频问题?调好这三个参数

当动画帧、指针移动、滚动等高频消息刷屏历史记录时,推荐调整以下选项(说明详见 devtools.md 配置章节):

参数 作用 默认值
excludeFromHistory 排除指定 Message 的 _tag 不记录历史(消息仍正常执行) 空
maxEntries 保留的最大记录条数,超出后淘汰最旧条目(取值 20~500) 100
keyframeInterval 每 N 条 Message 存一份完整 Model 快照;设为 1 后时间旅行可"零回放"直达 31

💡 小贴士:回放是从最近的快照开始重放 update 得到的。如果你的 update 逻辑昂贵、时间旅行感觉卡顿,把 keyframeInterval 设为 1,每条记录都拥有独立快照,跳转即开即达。

⚠️ 注意:excludeFromHistory 不是脱敏手段——被排除的消息仍然会改变 Model,历史快照里照样看得到结果。敏感数据要用 Effect 的 Redacted 类型处理。

六、让 AI Agent 也能"读档":DevTools MCP

同一份 Runtime 数据还通过 Model Context Protocol 暴露给 AI 编程助手:@foldkit/devtools-mcp 让 Agent 可以直接读取当前和历史 Model、对比两个状态、回放 UI,甚至向运行中的应用派发 Message。

  • 新项目由 create-foldkit-app 脚手架预装;老项目在项目根目录执行 npx @foldkit/devtools-mcp init 即可生成 .mcp.json
  • 常用工具包括 foldkit_get_model(读当前状态)、foldkit_diff_models(对比两个历史状态的差异)、foldkit_replay_to_keyframe(回放到任意保留状态)

完整工具列表见 packages/devtools-mcp/README.md 与 packages/website/src/page/aiMcp.md。

七、安全提醒:把密钥挡在状态树外

DevTools 会记录 Model、Message 载荷与 Command 参数,接入 MCP 后 Agent 也能读取这些数据。官方建议(devtools.md 安全章节):

  • API 密钥、长效 Token 等不要放进浏览器状态,应放在服务端边界之后
  • 浏览器必须短暂持有的敏感值,用 Effect 的 Redacted 包装,面板中会显示为 <redacted:access token>
  • 不需要 Agent 读取运行时数据时,可设置 devTools: false 或 devToolsMcpPort: false 关闭记录与桥接

八、总结

你的需求 DevTools 的解法
"页面状态不对,是哪步操作改坏的?" 时间线 + Model 标签页高亮变化路径
"我想回到那个错误现场仔细看" TimeTravel 模式回放 + Resume 恢复
"线上环境也要能查,但不能停应用" Inspect 模式 + show: 'Always'
"动画帧太多,历史被刷爆了" excludeFromHistory + maxEntries
"让 AI 助手帮我分析状态" DevTools MCP 服务器

Foldkit DevTools 把"状态发生了什么"从黑盒变成了可回放的时间轴——结合时间旅行调试能力,下一次再遇到"偶现"的状态 Bug,你只需要倒带回放,而不是反复猜测。

登录后查看全文
foldkit