Site DevTools 概览

Site DevTools 是 @docs-islands/vitepress 的运行时诊断界面。基础接入已经稳定之后，再用它看页面当前的渲染状态、包组成、HMR 时序，以及可选的构建报告。

什么时候打开它

当组件在切页时闪烁、页面资源突然变重、HMR 变慢，或者你需要把当前页的运行时快照发给同事、贴到 issue，或写进 PR 说明里时，就应该打开它。

入口与视图

入口与视图

打开 Site DevTools 后先选对说明视图

把 Site DevTools 当成说明文档来使用会更顺手：先确定问题，再去看负责解释它的那一部分。

如何进入

先通过 query 参数或文档站 logo 快捷方式打开 Site DevTools，后续就一直在同一个调试模式里切换不同视图即可。

选择通常很简单：组件本身的问题先看页面浮层，页面级运行时问题看 Debug Logs，需要构建证据时再看构建报告。

Query：?site-devtools=1。Shortcut：左上角 logo x3。Feedback：顶部 toast。

Query: ?site-devtools=1

Shortcut: 左上角 logo x3

Feedback: 顶部 toast

页面浮层

页面浮层把说明贴着当前组件本身展开。只要你关心的是实际渲染模式、当前阶段、耗时，或者最近一次 HMR 变化，就应该先从这里看起。

它也适合先做第一层归因，帮助判断当前容器的主要成本到底来自整体体积、JavaScript、CSS，还是资源文件。

Debug Logs

Debug Logs 面向运行时真相。它回答的不是“页面上发生了什么”，而是“当前页面运行时到底持有什么状态”。

当你需要查看 Injected Globals、渲染指标、HMR 指标，或者导出 snapshotRuntime() 结果发到 issue、PR、评论或交接说明里时，这里才是主入口。

构建报告

构建报告适合处理“只看运行时还不够”的情况，尤其是页面成本突然变重、构建回归需要解释时。

只要 analysis 已开启，这里就会给出 page-level 报告，并把同一套解释继续串到 chunk 和 module 证据上。

先用入口卡片打开调试模式，再按问题类型去选视图。大多数时候，你只是在三件事里做选择：看组件状态、看页面运行时，或者看构建证据。

核心能力

核心能力

三种视图，对应三类说明方式

每个视图更像一种解释路径，而不是一组独立的界面控件。

从组件本身开始说明

页面浮层

你会看到

页面浮层直接在当前容器附近解释问题，包括实际模式、当前阶段、耗时，以及最近一次 HMR 动作。

如果你只想先判断成本主要来自 JS、CSS、资源文件还是整体体积，这里也是最快的入口。

最适合

适合那些在切页、hydration 或交互初始化阶段就已经能看见症状的问题，先把范围缩到组件本身，再决定要不要继续看运行时。

主要输出

输出的是一份围绕当前组件的解释：到底跑了什么模式、走到了什么阶段、成本大概率落在哪一侧。

从运行时真相开始说明

Debug Logs

你会看到

Debug Logs 暴露的是页面级运行时状态，包括 Injected Globals、渲染指标、HMR 指标，以及收集到的运行时记录。

当你需要 snapshotRuntime() 这种可以拿去复制、比较、共享的结果时，这里比页面浮层更合适。

最适合

适合已经知道问题页面或问题组件在哪里，但需要更稳定的证据来分析、对比或分享给其他人。

主要输出

输出的是运行时快照本身，它更适合脱离界面继续讨论，尤其是在 issue、PR 评审和交接说明里。

从构建阶段开始说明

构建报告

你会看到

构建报告读取的是 docs build 期间生成的 page-level 分析结果，并把解释继续延伸到 chunk 和 module 证据。

最适合

适合页面成本变化需要构建期解释的场景，尤其是只看运行时症状还不足以说明回归原因的时候。

主要输出

输出的是一份以页面为中心的解释，把页面成本、chunk 证据和 module 证据串在一起。

只有开启构建期 analysis 后，这一部分才会出现。

下面这 3 张能力卡，覆盖了 Site DevTools 日常最常见的使用路径。重点不是把每个面板重新讲一遍，而是帮你更快判断第一眼该看哪里。

浏览器控制台辅助对象

如果你想直接检查或导出运行时状态，浏览器控制台里还会挂一个辅助对象：

globalThis.__DOCS_ISLANDS_SITE_DEVTOOLS__;

常用方法如下：

方法	用途
getEntries()	读取当前调试日志列表。
getGlobal(path?)	读取某个运行时全局对象，默认是 __COMPONENT_MANAGER__。
getRenderMetrics()	读取当前页面的渲染指标。
getHmrMetrics()	读取当前页面的 HMR 指标。
logRuntime(reason?)	把当前运行时快照写入调试日志。
snapshotRuntime()	直接返回当前运行时快照对象，适合复制和分享。

可选 UI 依赖

下面这些依赖只影响展示效果，核心诊断流程本身不依赖它们。

依赖	增强能力	缺失时的回退行为
vue-json-pretty	Injected Globals 和快照的树状 JSON 浏览	回退为可读的纯文本 JSON。
prettier	源码预览前的格式整理	直接显示原始源码文本。
shiki	语法高亮和更好的源码预览	保留纯文本预览。