Nuxt 4 开发教程

Appearance

预览 ​

npx nuxt preview ​

在本地预览生产构建，验证构建结果是否正确。

为什么要预览而不是直接用 nuxt dev？

nuxt dev 使用开发模式（HMR、源码映射、详细错误提示），行为与生产环境有差异。nuxt preview 使用生产构建，行为更接近线上环境，能提前发现问题。

bash
npx nuxt build
npx nuxt preview

默认在 http://localhost:3000 启动 Nitro 生产服务器。

常用选项 ​

bash
# 指定端口
npx nuxt preview --port 8080

# 指定主机（允许外部访问，如手机测试）
npx nuxt preview --host 0.0.0.0

# 指定环境变量文件
npx nuxt preview --dotenv .env.production

手动运行 ​

也可以直接运行构建输出：

bash
node .output/server/index.mjs

环境变量 ​

bash
# 设置端口
PORT=8080 node .output/server/index.mjs

# 设置主机
HOST=0.0.0.0 node .output/server/index.mjs

# 组合使用
PORT=8080 HOST=0.0.0.0 node .output/server/index.mjs

INFO

️ 环境变量修改后需要重启服务 不会像 nuxt dev 那样自动重载

Nitro 预览预设 ​

预览时默认使用 Node.js 预设。如果你的目标部署平台不同，可以在构建时指定：

bash
# 构建 Cloudflare Worker 版本并预览
NITRO_PRESET=cloudflare npx nuxt build
npx nuxt preview

# 构建 Deno 版本并预览
NITRO_PRESET=deno npx nuxt build
npx nuxt preview
预设预览命令
node (默认)node .output/server/index.mjs
bunbun run .output/server/index.mjs
denodeno run -A .output/server/index.mjs
cloudflarenpx wrangler dev .output/server/index.mjs

验证清单 ​

这是预览最重要的部分

很多问题只在生产构建中出现（如 Tree-shaking 移除了"看起来没用"的代码），开发时完全正常。

检查项说明如何验证
页面渲染SSR 页面是否正确输出访问各页面，查看 HTML 源码（Ctrl+U）
Hydration 不匹配服务端和客户端渲染结果不一致打开浏览器控制台，查看是否有 hydration 警告
API 路由服务端 API 是否正常响应用 Postman 或 curl 测试 API
静态资源图片、CSS、JS 是否正常加载检查 Network 面板，确认无 404
环境变量Runtime Config 值是否正确在页面中临时显示配置值验证
404 页面不存在的路由是否显示错误页面访问一个不存在的路径
重定向路由重定向和中间件是否生效测试重定向逻辑
性能首屏加载速度用 Lighthouse 检查

Hydration 不匹配排查 ​

什么是 Hydration 不匹配？

SSR 时服务端生成 HTML，客户端加载后 Vue 会尝试"接管"这些 HTML（Hydration）。如果客户端重新渲染的结果与服务端 HTML 不一致，就会报 Hydration 错误。

常见原因：

  1. 使用了 Date.now() 或 Math.random()（服务端和客户端结果不同）
  2. 依赖浏览器 API（window.innerWidth）在 SSR 时不可用
  3. 第三方库在 SSR/CSR 中渲染不同

解决方案：

  • 使用 <ClientOnly> 包裹仅客户端的内容
  • 使用 onMounted 延迟初始化依赖浏览器 API 的逻辑
  • 使用 <NuxtTime> 组件渲染时间（自动处理 SSR/CSR 差异）

性能验证 ​

bash
# 使用 lighthouse 检查性能
npx lighthouse http://localhost:3000 --output html --output-path ./report.html

# 检查构建产物大小
ls -lh .output/public/_nuxt/
du -sh .output/

性能指标参考 ​

指标目标值说明
FCP（首次内容绘制）< 1.8s用户首次看到内容的时间
LCP（最大内容绘制）< 2.5s主要内容完全加载的时间
CLS（累积布局偏移）< 0.1页面加载时内容位移量
TTI（可交互时间）< 3.8s页面可以交互的时间

TIP

如果 Lighthouse 分数不理想 检查：图片是否优化（<NuxtImg>）、JS 包是否过大（manualChunks）、是否有不必要的客户端渲染

注意事项 ​

  1. 先 build 再 preview：nuxt preview 需要 .output/ 目录，未构建会报错
  2. 不支持 HMR：预览是生产模式，修改代码后需要重新 nuxt build
  3. 环境变量：使用 .env 或系统环境变量，开发时的 .env 可能与生产不同
  4. 仅用于本地测试：生产部署不要使用 nuxt preview，应使用专业服务器（PM2、Docker 等）
  5. 静态生成用 nuxt generate：如果项目是纯静态站点（SSG），应使用 nuxt generate 生成后用静态服务器预览

常见问题 ​

问题原因解决方案
端口 3000 被占用其他服务使用了该端口使用 --port 8080 指定端口
环境变量不生效.env 文件路径不对使用 --dotenv 指定正确的环境文件
Hydration 警告SSR/CSR 渲染结果不一致用 <ClientOnly> 包裹仅客户端内容
静态资源 404构建不完整或路径错误重新 nuxt build，检查 baseURL 配置
API 返回 500服务端代码在生产环境表现不同检查 pm2 logs 或终端错误输出

基于 Nuxt 4 官方文档整理编写

MIT License