开发工具栏（Dev Toolbar）

开发服务器跑起来时，Astro 会在你本地浏览器预览的每个页面底部放一条开发工具栏（Dev Toolbar）。它是专门为”开发调试”准备的工具条，不会出现在你部署上线后的站点上。把鼠标悬停到页面底部就能看到它。

内置的四个工具

Astro Menu

Astro 菜单（Menu）提供当前项目的信息与资源入口：一键打开 Astro 文档、GitHub 仓库、Discord 社区。它还带一个”复制调试信息”按钮，背后调用的是 astro info 命令（第 42 章），把环境信息复制到剪贴板——向别人求助或提 issue 时特别有用。

Inspect

检查（Inspect）工具显示当前页面上所有**岛屿（island，第 26 章）**的信息：传给每个岛屿的属性（props）、以及它用的客户端指令（client directive，第 27 章）。想确认”某个交互组件到底有没有被水合、用了哪个指令”，看它就对了。

Audit

审计（Audit）工具会自动对当前页面跑一系列检查，专门揪最常见的性能和无障碍（accessibility）问题。发现问题，工具栏上会冒出一个红点；点开工具会弹出审计结果清单，并直接在页面上高亮相关元素。相当于内置了一个轻量的”体检仪”。

Settings

设置（Settings）工具让你配置开发工具栏本身，比如开详细日志、关掉通知、调整它在屏幕上的位置。

用集成扩展工具栏

除了内置四个，集成还能往工具栏里加新 app，给你项目专属的自定义工具。你可以在 Astro 集成市场按 “toolbar” 分类找更多可装的 app，或者通过 Astro 菜单直接发现。

安装这类”开发工具栏 app”集成，方式和装别的 Astro 集成完全一样（第 39 章），按它自己的安装说明来即可。有兴趣自己写一个？官方有”制作开发工具栏 app”的配方和 Dev Toolbar API 参考。

怎么关闭开发工具栏

开发工具栏默认每个站点都开。可按需关闭，分两种范围。

按项目关闭（所有人）

在 astro.config.mjs 里设 devToolbar.enabled = false，团队里每个人跑这个项目都不会看到它：

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  devToolbar: {
    enabled: false,
  },
});

想恢复，删掉这几行或改成 enabled: true。

按用户关闭（仅自己）

只想在自己机器上关掉，用 astro preferences 命令（第 42 章）：

astro preferences disable devToolbar

想在本机所有 Astro 项目都关，加 --global：

astro preferences disable --global devToolbar

之后用 astro preferences enable devToolbar 再打开。

调试群岛页面时的典型流程

假设你页面有个按钮点了没反应，用开发工具栏可以这样查：

1. 打开 Inspect，看那个组件是不是一个岛屿、用的哪个客户端指令。若没显示成岛屿，说明它根本没被水合——交互当然失效。
2. 打开 Audit，看有没有性能或无障碍问题拖后腿。
3. 打开 Astro Menu，点”复制调试信息”，把环境贴给帮你的人。

这三步覆盖了绝大多数”本地写代码时的卡点”。

怎么发现更多工具栏 app

开发工具栏的扩展来自集成。两种方式找：一是在 Astro 集成市场按 “toolbar” 分类筛选；二是直接点页面上的 Astro Menu，里面会推荐可装的 app。安装方式和装普通集成一样（第 39 章），按它的说明加到 integrations 即可。

Audit 具体查什么

Audit 工具重点查两类：性能（比如图片没加宽高导致布局抖动、请求过多）和无障碍（比如图片缺 alt、表单控件缺关联标签）。发现问题会在工具栏冒红点，点开列出清单，并在页面上高亮对应元素。它不能替代专业审计工具，但作为随手体检足够灵敏。

Settings 里能调什么

Settings 工具主要调工具栏自身的体验：开/关详细日志（verbose logging）、开/关通知、调整工具栏在屏幕上的位置（比如贴左还是贴右）。这些只影响你开发时的观感，不影响项目代码，放心按需调。

工具栏不显示怎么办

偶尔开发工具栏不出现，常见原因：浏览器装了拦截覆盖层的扩展、或项目被设了 devToolbar.enabled = false。先确认配置没关它；再试试无痕窗口排除扩展干扰。它是”开发体验”工具，不是功能必需项，关键时刻不影响你写代码，只是少了调试帮手。

它和浏览器开发者工具的关系

开发工具栏不是要取代浏览器的开发者工具（F12），而是和它互补。浏览器 DevTools 看网络、看 DOM、看性能面板；Astro 开发工具栏则聚焦”Astro 专属”信息：岛屿有没有水合、action 调用、内容集合、集成状态等。两者一起开，排查问题最顺。工具栏里 Audit 标出的问题，往往也能在 DevTools 的渲染面板里进一步追细节。

你可能还想问

• 工具栏会影响线上速度吗？ 不会。它只在 astro dev 时注入，构建产物里完全没有它，所以装再多工具栏 app 也不增加线上体积。
• 别人访问我的站点会看到吗？ 看不到。开发工具栏只在你本机跑开发服务器时出现，部署上去的站点对访客不可见。
• 为什么有的项目没有 Inspect？ 多半是那个页面没有任何岛屿（纯静态内容），没东西可检查；有交互组件的水合页面才会显示岛屿信息。

小结

开发工具栏是本地调试帮手，线上不出现。内置四个工具：Astro Menu（资源 + 复制调试信息）、Inspect（看岛屿与指令）、Audit（性能/无障碍体检）、Settings（配置自身）。集成能往里加新 app；不想要可用配置或 astro preferences 关掉。它和 VS Code 扩展一起，构成 Astro 的开发体验双翼。

下一章是本章块的压轴：动作 Actions——一种比手写 API 端点更省事的后端调用方式。