Foldkit DevTools完全指南:用时间旅行调试快速定位每一次状态变化
Foldkit DevTools完全指南:用时间旅行调试快速定位每一次状态变化
Foldkit DevTools 是 Foldkit 框架内置的浏览器调试面板,通过时间旅行调试(Time-Travel)能力,让你像倒带视频一样回放到任意一次状态变化,快速定位"页面为什么变成这样"。它记录流经应用的每一条 Message,并保存对应的 Model 快照,无需打断点、无需 console.log,一次点击就能回到问题发生前的那一刻。
一、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
- 打开面板:找到页面右下角的 DevTools 标签页并展开
- 定位可疑 Message:在时间线中找到异常发生前的那一条,右侧会标注该条消息耗时
- 切换检查器:
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。
五、高频问题?调好这三个参数
当动画帧、指针移动、滚动等高频消息刷屏历史记录时,推荐调整以下选项(说明详见 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,你只需要倒带回放,而不是反复猜测。

