---
title: "nuxt dev"
description: "dev 命令会在 http://localhost:3000 启动一个支持热模块替换的开发服务器"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/commands/dev"
---
# nuxt dev

> dev 命令会在 http://localhost:3000 启动一个支持热模块替换的开发服务器

<!--dev-cmd-->

```bash [Terminal]
npx nuxt dev [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv=<path>...] [--envName=<environment>] [-e, --extends=<layer-name>...] [--inspect] [--inspect-brk] [--tui] [--clear] [-f, --fork] [-p, --port=<port>] [--takeover] [--strictPort] [-h, --host=<host>] [-o, --open] [--open.url=<url|path>] [--clipboard] [--qr] [--tunnel] [--public] [--publicURL=<url>] [--https] [--https.cert=<path>] [--https.key=<path>] [--https.pfx=<path>] [--https.passphrase=<passphrase>] [--https.validityDays=<days>] [--https.domains=<domain>...] [--profile=<verbose>]
```

<!--/dev-cmd-->

`dev` 命令会在<http://localhost:3000>启动一个支持热模块替换的开发服务器

![nuxt dev](https://raw.githubusercontent.com/zhcndoc/nuxt-cli/main/capture/output/nuxt-dev-static.svg)

## 参数

<!--dev-args-->

| 参数        | 描述                |
| --------- | ----------------- |
| `ROOTDIR` | Nuxt 项目的根目录（默认：.） |

<!--/dev-args-->

## 选项

<!--dev-opts-->

| 选项                                   | 默认值     | 描述                                                                               |
| ------------------------------------ | ------- | -------------------------------------------------------------------------------- |
| `--cwd=<directory>`                  |         | 指定 Nuxt 项目的根目录                                                                   |
| `--logLevel=<silent\|info\|verbose>` |         | 指定构建时的日志级别                                                                       |
| `--dotenv=<path>...`                 |         | 要加载的 `.env` 文件路径，相对于根目录。可以重复指定，后面的文件优先级更高。                                       |
| `--envName=<environment>`            |         | 解析配置覆盖项时使用的环境（构建时默认为 `production`，运行 dev 服务器时默认为 `development`）                  |
| `-e, --extends=<layer-name>...`      |         | 从 Nuxt layer 扩展                                                                  |
| `--inspect`                          |         | 为服务器代码启用 Node.js 检查器（`--inspect=[host:]port`），并在下一个端口为 CLI 进程启用检查器               |
| `--inspect-brk`                      |         | 类似于 `--inspect`，并在加载 Nuxt 前等待调试器连接到 CLI 进程（`--inspect-brk=[host:]port`）          |
| `--tui`                              | `true`  | 交互式终端 UI（固定状态面板、折叠日志和单键快捷键）                                                      |
| `--no-tui`                           |         | 禁用交互式终端 UI，改为直接输出日志                                                              |
| `--clear`                            | `false` | 重启时清除控制台                                                                         |
| `-f, --fork`                         | 取决于运行时  | 从 fork 出来的子进程提供应用服务（在运行时支持的情况下默认启用）                                              |
| `--no-fork`                          |         | 禁用 fork 模式                                                                       |
| `-p, --port=<port>`                  |         | 监听端口（默认值：`NUXT_PORT \|\| NITRO_PORT \|\| PORT \|\| nuxtOptions.devServer.port`）  |
| `--takeover`                         |         | 停止此项目中已运行的 dev 服务器并接管其位置                                                         |
| `--no-takeover`                      |         | 永不停止此项目中已运行的 dev 服务器                                                             |
| `--strictPort`                       | `false` | 如果请求的端口不可用，则退出而不是使用其他端口                                                          |
| `-h, --host=<host>`                  |         | 监听主机（默认值：`NUXT_HOST \|\| NITRO_HOST \|\| HOST \|\| nuxtOptions.devServer?.host`） |
| `-o, --open`                         | `false` | 在浏览器中打开 URL                                                                      |
| `--open.url=<url\|path>`             |         | 要打开的路径或 URL，而不是 dev 服务器根目录                                                       |
| `--clipboard`                        | `false` | 将 URL 复制到剪贴板                                                                     |
| `--qr`                               |         | 打印公开 URL 的二维码（有可用 URL 时默认启用）                                                     |
| `--tunnel`                           |         | 通过 Cloudflare quick tunnel 暴露服务器                                                 |
| `--public`                           |         | 监听所有网络接口并允许任意主机连接                                                                |
| `--publicURL=<url>`                  |         | 要显示的公开 URL（用于二维码和剪贴板）                                                            |
| `--https`                            |         | 使用本地信任的开发证书启用 HTTPS                                                              |
| `--https.cert=<path>`                |         | TLS 证书路径                                                                         |
| `--https.key=<path>`                 |         | TLS 密钥路径                                                                         |
| `--https.pfx=<path>`                 |         | PKCS#12（.p12/.pfx）密钥库路径                                                          |
| `--https.passphrase=<passphrase>`    |         | TLS 密钥或密钥库的密码                                                                    |
| `--https.validityDays=<days>`        |         | 生成的自签名证书的有效天数                                                                    |
| `--https.domains=<domain>...`        |         | 生成的证书的域名。可以重复指定，也可以使用逗号分隔的列表。                                                    |
| `--profile=<verbose>`                |         | 分析性能，在退出时写入 V8 CPU profile 和 JSON 报告。使用 `--profile=verbose` 可将完整报告打印到控制台。        |

<!--/dev-opts-->

也可以通过 `NUXT_PORT`、`NITRO_PORT`、`PORT`、`NUXT_HOST`、`NITRO_HOST` 或 `HOST` 环境变量设置端口和主机。

此命令会将 `process.env.NODE_ENV` 设置为 `development`。

## 交互式终端 UI

在交互式终端中，`nuxt dev` 会渲染一个固定面板：服务器 URL、启动进度、当前状态和一行快捷键，其上方的日志会折叠显示。当输出不是终端输出、处于 CI 环境、连接了调试器或终端过小时，它会回退为普通的日志流。

| 按键        | 操作                |
| --------- | ----------------- |
| `r`       | 重启 dev 服务器        |
| `shift-r` | 使用已清除的缓存重启        |
| `o`       | 在浏览器中打开应用         |
| `y`       | 将服务器 URL 复制到剪贴板   |
| `i`       | 显示版本、URL、二维码和会话信息 |
| `l`       | 浏览日志历史            |
| `e`       | 打开最后一个错误处的日志      |
| `n`       | 浏览已提供服务的请求        |
| `p`       | 浏览页面和服务器路由        |
| `c`       | 清除日志、请求和控制台       |
| `?`       | 显示所有快捷键           |
| `q`       | 退出                |

在视图中，`y` 会复制选中的行，`shift-y` 会复制筛选条件和搜索结果留下的所有行；如果内容过多而无法粘贴，则保留最新的行。在信息视图中，`shift-y` 会改为复制 [`nuxt info`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/info) 表格。

### 追踪请求

在网络视图（`n`）中选中一个请求并按 `enter`，即可查看它的耗时分布。追踪会在同一条时间线上绘制服务器为该请求执行的所有操作：路由中间件、服务器路由处理程序、Nuxt 插件、钩子、数据获取、渲染，以及应用向其他服务器发出的请求。时间线下方会列出 Vite 为该请求编译模块所花的时间，并按 Vite 插件和最慢模块细分，随后显示该请求产生的日志。

追踪基于 Nuxt 和 Nitro 发布的 [tracing channels](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel)，因此展示内容取决于所用版本。`nuxt dev` 会为你启用 `tracingChannel` 选项；如要退出，请在 `nuxt.config` 中设置 `tracingChannel: false`。

### 禁用 UI

传入 `--no-tui` 或设置 `NUXT_TUI=plain`，即可改为流式输出日志。也可以传入 `NUXT_TUI=1` 强制启用 UI（如果输出通过管道传输或重定向，该设置不起作用）。

![带有普通输出的 nuxt dev](https://raw.githubusercontent.com/zhcndoc/nuxt-cli/main/capture/output/nuxt-dev-plain-static.svg)

普通输出提供的快捷键更少：`r` 重启，`o` 打开，`u` 显示 URL，`qr` 显示二维码，`copy` 复制 URL，`c` 清除控制台，`h` 获取帮助，`q` 退出。

## 重启

当 dev 服务器重新加载或重启时，它会说明触发原因；对 `nuxt.config` 的更改还会列出实际不同的键，因此可以区分仅由格式更改触发的重启和更改了配置的重启。重新加载会在原进程中进行；重启会替换进程，这是更改 `nuxt.config` 或已安装依赖所需的操作。

## 接管正在运行的 dev 服务器

dev 服务器会将自身记录在[构建目录](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt)中的 `nuxt.lock` 内，因此同一项目的第二个 `nuxt dev` 会报告已经运行的服务器，而不是与其争抢端口。传入 `--takeover` 可停止它并接管其位置，或设置 `NUXT_IGNORE_LOCK=1` 以无论如何运行第二个服务器（不受支持）。

[`nuxt curl`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/curl) 和 [`nuxt task`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/task) 也是通过同一个锁文件查找要与之通信的服务器。

## HTTPS

`--https` 会通过 TLS 提供服务：安装了 `mkcert` 时使用它生成本地信任的证书，否则生成自签名证书。`--https.cert` 和 `--https.key` 使用已有证书，`--https.pfx` 与 `--https.passphrase` 则使用 PKCS#12 密钥库。

::note
Node 不会读取系统信任存储，因此从 Node 向使用生成证书的服务器发出的请求不会信任该证书。请将 `NODE_EXTRA_CA_CERTS` 设置为签发该证书的证书颁发机构。
::

## 调试

`--inspect` 会为服务器代码启用 Node.js 检查器：服务器路由、中间件和服务端渲染，这些代码运行在 Nitro worker thread 中。它接受可选的 `[host:]port`，默认值为 `127.0.0.1:9229`，因此 Chrome DevTools（`chrome://inspect`）和大多数编辑器无需配置即可找到它。服务器重新加载时，调试器会自动重新连接。

### 调试 CLI

`nuxt.config`、模块和构建钩子则在 CLI 进程中运行，该进程会在下一个端口启用自己的检查器（默认为 `9230`）。在 `chrome://inspect`（**Configure...**）中将 `localhost:9230` 添加为目标，或将编辑器指向该地址。

若要调试 Nuxt 加载时运行的代码，请使用 `--inspect-brk`。CLI 进程会在加载 Nuxt 前等待调试器连接到下一个端口：

```bash
npx nuxt dev --inspect-brk
```

`--profile` 会在进程退出时，将 V8 CPU profile 写入项目中的 `nuxt-dev.cpuprofile`。`--profile=verbose` 还会将完整报告打印到控制台。

::note
构建计时、`perf-report.json` 和 `perf-trace.json` 来自 Nuxt 自带的构建性能分析功能，该功能需要 Nuxt v4.4 或更高版本。在更早版本中仍会写入 CPU profile。
::

## 环境变量

| 变量                              | 用途                             |
| ------------------------------- | ------------------------------ |
| `NUXT_PORT`、`NITRO_PORT`、`PORT` | 按此优先级顺序监听端口                    |
| `NUXT_HOST`、`NITRO_HOST`、`HOST` | 按此优先级顺序监听主机                    |
| `NUXT_TUI`                      | `1` 强制开启交互式 UI，`plain` 选择退出    |
| `NUXT_TERM_THEME`               | 当无法检测终端背景时，使用 `light` 或 `dark` |
| `NUXT_IGNORE_LOCK`              | `1` 忽略当前项目中已经运行的 dev 服务器       |
| `NUXT_IGNORE_UPDATE_CHECK`      | `1` 停止 CLI 检查更新版本的 Nuxt        |

---

- [来源](https://github.com/nuxt/cli/blob/main/packages/nuxt-cli/src/commands/dev.ts)


## Sitemap

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