开发服务器

为什么需要了解开发服务器？

开发服务器是你写代码时最常打交道的东西。了解它能做什么、怎么配置，可以帮你：

遇到端口冲突时快速解决
在手机上预览你的开发页面
理解为什么改了代码页面会自动更新
知道什么时候需要重启，什么时候不需要

启动开发服务器

bash

# 推荐：通过 npm scripts 启动
npm run dev

# 或通过 npx 临时执行
npx nuxt dev

默认在 http://localhost:3000 启动。

INFO

️ 不要直接运行 nuxt dev：nuxt 是项目本地依赖（安装在 node_modules/.bin/ 中）不是全局命令。直接输入 nuxt dev 会报 bash: nuxt: command not found。必须通过 npm run dev 或 npx nuxt dev 来运行

方式	命令	说明
npm scripts（推荐）	`npm run dev`	使用 `package.json` 中定义的脚本
npx	`npx nuxt dev`	临时执行本地安装的 nuxt
全局安装（不推荐）	`npm install -g nuxt`	版本可能与项目不一致

开发服务器做了什么？

启动一个本地 HTTP 服务器
编译你的 Vue 组件、TypeScript、CSS 等代码
提供 Vite 的 HMR（热模块替换）能力
在 SSR 模式下，还启动了一个 Node.js 服务端来渲染页面

所以你在浏览器看到的不是"静态 HTML"，而是 Nuxt 服务端渲染后的结果。

常用选项

bash

# 指定端口
npx nuxt dev --port 8080

# 指定主机地址（允许外部访问——手机、其他电脑）
npx nuxt dev --host 0.0.0.0

# 指定 HTTPS（某些功能如 Cookie 需要安全上下文）
npx nuxt dev --https

# 使用自定义 SSL 证书
npx nuxt dev --https --ssl-cert cert.pem --ssl-key key.pem

# 指定环境文件
npx nuxt dev --dotenv .env.development

# 禁用 Tortoise 缓存（调试时使用）
npx nuxt dev --tunnel

什么时候用 --host 0.0.0.0？

当你想在手机或其他设备上预览你的开发页面时。默认只允许本机（localhost）访问，加上这个参数后，同一局域网内的设备都可以通过你的 IP 访问。

使用方法：

运行 nuxt dev --host 0.0.0.0
终端会显示类似 Network: http://192.168.1.100:3000
手机浏览器打开这个地址即可

热模块替换（HMR）

Nuxt 使用 Vite 作为默认构建工具，提供极速的 HMR：

修改内容	HMR 行为	是否需要重启
Vue 组件的 `<template>`/`<script>`/`<style>`	即时生效	❌ 不需要
CSS/SCSS 样式文件	即时生效	❌ 不需要
`server/api/` 下的 API 路由	自动重载	❌ 不需要
`app/composables/` 下的组合式函数	即时生效	❌ 不需要
`nuxt.config.ts` 配置文件	需要重启	✅ 需要
`app/app.vue` 根组件	需要重启	✅ 需要

HMR 是什么？

Hot Module Replacement 的缩写。它让你修改代码后，浏览器不需要刷新页面就能看到变化。你的表单数据、滚动位置等状态都会保留。

对比没有 HMR 的时候：改一行代码 → 刷新页面 → 重新填写表单 → 再改 → 再刷新…… 非常痛苦。

INFO

️ 什么情况 HMR 不生效？

修改了 nuxt.config.ts（配置文件变更需要重启整个服务器）
新增/删除了 app/pages/ 下的文件（有时需要手动刷新浏览器）
文件名包含特殊字符（中文名等）
如果 HMR 经常失灵，试试 nuxt cleanup 清理缓存后重启

nuxt.config.ts 中配置开发服务器

export default defineNuxtConfig({
  devServer: {
    port: 8080,         // 端口
    host: '0.0.0.0',   // 主机（允许外部访问）
    https: true,        // 启用 HTTPS
  },
})

命令行参数 vs 配置文件

命令行参数（nuxt dev --port 8080）是临时的，每次都要输入
配置文件是永久的，写一次就好
如果两者同时设置，命令行参数优先

开发工具

Nuxt DevTools

Nuxt 内置开发者工具，默认开启。在浏览器页面底部可以看到 Nuxt 图标，点击即可打开：

功能	说明	什么时候用
页面组件树	查看当前页面的组件层级	想知道某个 UI 对应哪个组件
路由信息	查看当前路由、参数、中间件	路由跳转不正常时排查
Payload 数据	查看 SSR 传递的数据	数据不显示或显示错误时排查
自动导入列表	查看所有自动导入的组件/函数	忘了组件名或想确认是否自动导入
Pinia 状态	查看/修改状态管理数据	调试状态相关问题
服务端数据	查看服务端日志	排查 API 请求问题

如需禁用：

export default defineNuxtConfig({
  devtools: { enabled: false },
})

新手建议

保持 DevTools 开启。它是你最好的调试伙伴，尤其是你不确定某个组件叫什么名、某个数据从哪来的时候。

Vue DevTools

安装浏览器插件 Vue.js DevTools 可以更深入地调试 Vue 组件。

Nuxt DevTools vs Vue DevTools 的区别

Nuxt DevTools：关注 Nuxt 特有的东西（路由、自动导入、Payload、服务端）
Vue DevTools：关注 Vue 组件本身（props、emits、响应式数据、DOM）
两者互补，推荐都安装

常见问题

端口被占用

bash

# 方法1：查看占用端口的进程
lsof -i :3000
# 然后 kill 掉对应的进程

# 方法2：直接用其他端口
npx nuxt dev --port 3001

为什么端口会被占用？

通常是之前的开发服务器没有正确关闭（比如直接关了终端窗口）。养成良好的习惯：用 Ctrl+C 停止开发服务器。

HMR 不生效

排查步骤：

确认文件在正确的目录下（app/ 下，不是根目录）
确认文件名没有特殊字符
尝试重启开发服务器
如果还是不行，清理缓存后重启：

bash

npx nuxt cleanup
npm run dev

首次启动慢

首次启动会执行 nuxt prepare 生成类型和模板，后续启动会快很多。如遇到问题：

bash

npx nuxt cleanup   # 清理缓存
npx nuxt prepare   # 重新生成
npm run dev         # 再启动

.nuxt/ 目录是什么？

这是 Nuxt 自动生成的临时目录，包含：

类型声明（.d.ts）
生成的路由配置
自动导入信息
模板文件

不要手动编辑这个目录的内容

也不要把它提交到 Git（已在 .gitignore 中）。每次启动都会重新生成。

页面显示空白

检查终端是否有报错
检查浏览器控制台（F12）是否有报错
确认 app/app.vue 中有 <NuxtPage />
确认 app/pages/ 目录下有 index.vue

知识脉络

text

安装与创建项目 → 你在这里：开发服务器
                   │
                   ├─→ 下一步：第一个页面
                   │
                   └─→ 相关：项目配置（了解 nuxt.config.ts）

开发服务器 ​

为什么需要了解开发服务器？ ​

启动开发服务器 ​

常用选项 ​

热模块替换（HMR） ​

nuxt.config.ts 中配置开发服务器 ​

开发工具 ​

Nuxt DevTools ​

Vue DevTools ​

常见问题 ​

端口被占用 ​

HMR 不生效 ​

首次启动慢 ​

页面显示空白 ​

知识脉络 ​

开发服务器

为什么需要了解开发服务器？

启动开发服务器

常用选项

热模块替换（HMR）

nuxt.config.ts 中配置开发服务器

开发工具

Nuxt DevTools

Vue DevTools

常见问题

端口被占用

HMR 不生效

首次启动慢

页面显示空白

知识脉络