---
title: "Nuxt DevTools v4"
description: "Nuxt DevTools v4 基于 Devframe 和 Vite DevTools 构建，将完整的 Vue DevTools 及更广泛的开发者工具生态带入 Nuxt。"
canonical_url: "https://nuxt.zhcndoc.com/blog/devtools-v4"
---
# Nuxt DevTools v4

> Nuxt DevTools v4 基于 Devframe 和 Vite DevTools 构建，将完整的 Vue DevTools 及更广泛的开发者工具生态带入 Nuxt。

我们很高兴地宣布 [Nuxt DevTools v4](https://github.com/nuxt/devtools) 发布。

Nuxt DevTools v4 基于 [Devframe](https://github.com/devframes/devframe) 和 [Vite DevTools](https://github.com/vitejs/devtools) 构建。因此，Nuxt 现在可以复用整个开发者工具生态。我们也不再将 Vue DevTools 复制进项目；现在您可以使用功能完整的 Vue DevTools。

::tip
Nuxt DevTools v4 随 Nuxt v5 一同发布，也可用于 Nuxt v4.5+。请参阅[在 Nuxt v4 中使用](#use-it-with-nuxt-v4)。
::

应用无需做任何更改。您可以像以前一样打开 DevTools。快捷键为 macOS 上的 `Shift + Option + D`，或 Windows 上的 `Shift + Alt + D`。

## 为什么重建

自 [v1.0](https://nuxt.zhcndoc.com/blog/nuxt-devtools-v1-0) 以来，Nuxt DevTools 的发展方式逐渐变得只适用于 Nuxt。每个想要添加面板的模块都必须使用我们自己的 API；Vue DevTools 的每项功能也都需要复制到我们的代码中。这不仅增加了大量工作，也让同步更新变得困难。

我们希望从根本上解决这个问题。这并非 Nuxt 独有的问题：JavaScript 生态中的各种工具都需要面板、与服务器通信的方式，以及展示数据的方式。我们一直希望[实现一个通用、统一的开发者工具体验](https://devfra.me/posts/pluggable-extensible-playful-devtools)，让整个生态能够共享并在此基础上继续构建。

因此，我们构建了 Devframe，一个与框架无关、支持智能代理的开发者工具套件。如今，Vite DevTools、Vue DevTools 和 Nuxt DevTools 都运行在它之上。

## 什么是 Devframe

Devframe 是一套用于构建开发者工具的套件，不依赖任何特定框架或工具。您只需定义一次开发者工具及其面板、类型化 RPC 和共享状态，同一份定义便可运行于任意宿主：Nuxt、Vite、Next.js、独立 CLI、静态报告，或面向编程代理的 MCP 服务器。可以把它看作开发者工具领域的 [`unplugin`](https://unplugin.unjs.io/)。

在底层，devframe 会以普通的 `Request` → `Response` 处理器形式公开，hub 则可以通过一个处理器组合多个 devframe。更多信息请参阅 [Devframe 仓库](https://github.com/devframes/devframe)及其[发布文章](https://devfra.me/posts/pluggable-extensible-playful-devtools)。

## 统一的生态

从 v4 开始，Nuxt 加入了与 Vite 及其他工具相同的生态系统。这带来两个方向的兼容：

- 其他工具基于 Devframe 或 Vite DevTools 构建的开发者工具，现在也可以在 Nuxt 应用中使用。
- 您为 Nuxt 构建的开发者工具，现在也可以在 Nuxt 之外运行。

![通用开发者工具生态：通用、构建工具、框架专属和生态系统工具可组合到各类宿主中](https://nuxt.zhcndoc.com/assets/blog/devtools-v4/devtools-ecosystem.png)

上图展示了这些部分如何在 Nuxt 中组合。面板中的大多数功能都不是专为 Nuxt 编写的。无障碍检查、终端和数据检查器等工具属于通用层，因此每个宿主都能使用。Vitest、Rolldown 和 Oxlint 等 Vite 工具则随构建工具提供。只有 Vue 组件和响应式系统、Pinia，或 Nuxt 模块和自动导入等内容属于框架专属层。UnoCSS、ESLint Config Inspector 等社区工具也能以相同方式接入。

::video
```yaml [props]
src: https://nuxt.zhcndoc.com/assets/blog/devtools-v4/nuxt-devtools-compose.mp4
controls: true
autoplay: true
loop: true
muted: true
class: rounded-lg
```
::

其他宿主可以选择自己的组合。Next.js 或 Svelte 的 DevTools 可以复用相同的通用层和构建工具层，只需添加各自的框架专属部分。这样新宿主一开始就拥有丰富的工具，而您编写的每个工具也能触达更多用户。

一次构建面板，即可供更多人使用。

## 完整的 Vue DevTools 和 Vite DevTools

得益于 Devframe，最新版 Vue DevTools 和 Vite DevTools 现在都完整地构建于其上。整个技术栈包含三层，每一层都会继承并扩展其下层：

- **Devframe Hub** 是基础层，通过一个标准处理器组合可移植的 devframe。
- **Vite DevTools** 构建于 hub 之上，为 Vite 工具链加入 Vite 插件、Vitest、Rolldown 和 Oxc 等工具。
- **Nuxt DevTools** 构建于 Vite DevTools 之上，并加入 Nuxt 层：Vue DevTools、Pinia、Nuxt 模块、自动导入等。

![Vite 和 Nuxt DevTools 技术栈：Devframe Hub、Vite DevTools 和 Nuxt DevTools 逐层继承并扩展](https://nuxt.zhcndoc.com/assets/blog/devtools-v4/nuxt-devtools-stack.png)

因此我们不再需要将 Vue DevTools 复制到项目中。Nuxt DevTools 会继承其功能，您始终可以使用完整且最新的 Vue DevTools。Vite DevTools 的改进也无需我们额外处理，就能同步到 Nuxt。

在底层，每个开发者工具都是一个 devframe，可以独立运行、加入 hub，或通过相同的标准处理器挂载到任意宿主。Vite DevTools 是其中一个宿主，而 Vue DevTools 和 Nuxt DevTools 等框架专属宿主则继承并扩展它。

![一个 devframe，多种运行方式：同一份 devframe 定义可独立运行、加入 hub，或通过标准处理器挂载到任意宿主框架](https://nuxt.zhcndoc.com/assets/blog/devtools-v4/devtools-inherit.png)

## 过渡版本

尽管底层架构经历了全面改造和重组，用户体验仍保持一致。我们始终致力于逐步发布，让迁移过程更加顺畅。

**Nuxt DevTools v4 是一个过渡版本。**

我们知道许多模块都在使用 `@nuxt/devtools-kit` 中旧版 Nuxt DevTools API。如果您的模块使用了该 API，在 v4 中仍可继续运行。我们添加了兼容层，将旧 API 映射到新系统。开发期间，兼容层会输出警告，提示您需要更新哪个模块。

## 面向模块作者

兼容层只是为迁移争取时间。我们建议您将模块迁移到以下新 API 之一：

- 如果希望面板适用于 Nuxt、Vite、Next.js、独立 CLI 或 MCP 服务器等任意工具，请使用 **Devframe**。
- 如果模块只适用于 Vite，且您希望尽量少改动，请使用 **Vite DevTools**。Nuxt DevTools v4 会直接提供 Vite DevTools 上下文。

### 快速迁移

The old `@nuxt/devtools-kit` helpers map to the new context one by one. Each deprecated helper now logs a diagnostic code, so you can find the exact call to update:

| Before (`@nuxt/devtools-kit`) | After (`onDevtoolsReady`)                            | Warning        |
| ----------------------------- | ---------------------------------------------------- | -------------- |
| `addCustomTab()`              | `ctx.docks.register()`                               | `NDT_DEP_0005` |
| `refreshCustomTabs()`         | update the handle returned by `ctx.docks.register()` | `NDT_DEP_0006` |
| `extendServerRpc()`           | `ctx.scope('my-module').rpc.register()`              | `NDT_DEP_0003` |
| `startSubprocess()`           | `ctx.terminals.startChildProcess()`                  | `NDT_DEP_0004` |

下面展示了将面板迁移到 Vite DevTools 上下文之前和之后的代码：

```ts [迁移前]
import { addCustomTab, extendServerRpc } from '@nuxt/devtools-kit'

export default defineNuxtModule({
  setup() {
    addCustomTab({
      name: 'my-module',
      title: 'My Module',
      icon: 'carbon:apps',
      view: { type: 'iframe', src: '/__my-module/' },
    })

    extendServerRpc('my-module', {
      getModules: () => loadModules(),
    })
  },
})
```

```ts [迁移后]
import { onDevtoolsReady } from '@nuxt/devtools-kit'

export default defineNuxtModule({
  setup() {
    onDevtoolsReady((ctx) => {
      ctx.docks.register({
        id: 'my-module',
        title: 'My Module',
        icon: 'carbon:apps',
        type: 'iframe',
        url: '/__my-module/',
      })

      ctx.scope('my-module').rpc.register({
        name: 'get-modules', // registered as `my-module:get-modules`
        type: 'query',
        handler: () => loadModules(),
      })
    })
  },
})
```

::note
目前 docks 宿主尚不支持 `vnode` 视图和标签分类。如果您的模块依赖这些功能，请暂时继续使用兼容层。
::

::tip
请阅读[模块迁移指南](https://devtools.nuxt.com/module/migration-v4)了解详情。
::

### 使用 Devframe 实现可移植性

如果希望工具能在 Nuxt 之外运行，可以使用 `defineDevframe()` 定义一次，并让 Nuxt 模块只保留薄封装。RPC 函数具有类型定义，可通过任意 [Standard Schema](https://standardschema.dev/) 库进行验证，并以 devframe id 作为命名空间：

```ts [src/devframe.ts]
import { defineDevframe, defineRpcFunction } from 'devframe'
import * as v from 'valibot'

const getModules = defineRpcFunction({
  name: 'get-modules',
  type: 'query',
  args: [v.object({ limit: v.number() })],
  returns: v.array(v.object({ id: v.string(), size: v.number() })),
  handler: async ({ limit }) => (await loadModules()).slice(0, limit),
})

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  icon: 'ph:gauge-duotone',
  clientAssets: 'client/dist',
  setup(ctx) {
    ctx.scope('my-tool').rpc.register(getModules)
  },
})
```

之后，您可以通过适合用户的任意入口发布同一份定义：

```ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCac } from 'devframe/adapters/cac'
import { createMcpServer } from 'devframe/adapters/mcp'
import devframe from './devframe'

export const vitePlugin = createPluginFromDevframe(devframe) // Vite DevTools, and therefore Nuxt
export const runCli = () => createCac(devframe).parse() // standalone CLI
export const buildReport = () => createBuild(devframe, { outDir: 'dist-static' }) // static report
export const startMcp = () => createMcpServer(devframe, { transport: 'stdio' }) // for coding agents
```

如果工具界面是 Nuxt 应用，[`@devframes/nuxt/single`](https://github.com/devframes/devframe) 可以将其接入 devframe 的浏览器端，并在 `useNuxtApp()` 中提供带类型的 `$rpc` 客户端。

请查看 [Devframe 文档](https://github.com/devframes/devframe)，了解详情及从零构建数据检查器的分步教程。

## 试用

体验 Nuxt DevTools v4 最简单的方式是[使用 Nuxt 5](https://nuxt.zhcndoc.com/docs/5.x/getting-started/upgrade#migrating-to-nuxt-5)，因为 Nuxt 5 默认附带 DevTools v4。

### 在 Nuxt v4 中使用

如果您使用 Nuxt v4.5+ 并想试用 Nuxt DevTools v4，可以将它作为模块添加：

```bash
npx nuxt module add @nuxt/devtools@4
```

## 致谢

没有 Devframe、Vite DevTools 和 Vue DevTools 背后团队的支持，就不会有这个版本。
感谢所有参与构建 Devframe 并促成这些工具协同工作的贡献者。

欢迎试用新版 Nuxt DevTools，并告诉我们您的想法。您也可以在 [GitHub](https://github.com/nuxt/devtools/issues) 提交问题。

祝调试愉快！


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.