首页 / Nuxt 4 入门教程 / 构建与部署

← 上一篇 下一篇 →
Nuxt 4 入门教程

构建与部署

本教程共 50 篇 · 第 46 篇 · 更新于 2026-08-08 · 约 8 分钟阅读

NuxtNuxt4部署buildnode-server静态托管presetVercel

本节目标：理解 Nuxt 应用有哪几种部署形态，会用 nuxt build 产出对应产物，并了解常见云平台的 preset 配置。

46-1

不管部署到哪里，第一步都是构建：

npx nuxt build

构建完成后，产物在 .output/ 目录。Nuxt 底层由 Nitro 负责打包，所以「部署到哪」本质上由 Nitro 的 preset（预设） 决定。同一个源码，换 preset 就能产出适配不同平台的产物。

Note

部署形态分三大类：Node.js 服务器、静态托管、无服务器/边缘（CDN）环境。选哪种，取决于你的渲染模式和托管商。

46-2

这是 Nitro 的默认输出格式（不指定 preset 时）。它会产出一个就绪的 Node 服务入口：

NODE_ENV=production node .output/server/index.mjs

默认监听 3000 端口，可用环境变量调整：

  • NITRO_PORT / PORT（默认 3000）
  • NITRO_HOST / HOST（默认 0.0.0.0）
Warning

跑生产服务务必设 NODE_ENV=production。否则依赖（如 Vue Router）不会剥离开发期警告，日志会被一堆 [Vue Router warn] 刷屏。

想用多进程提升吞吐，可选 node_cluster preset：

NITRO_PRESET=node_cluster nuxt build

用 PM2 托管也很常见，写个 ecosystem.config.cjs 即可：

module.exports = {
  apps: [
    {
      name: 'NuxtApp',
      exec_mode: 'cluster',
      instances: 'max',
      script: './.output/server/index.mjs',
      env: { NODE_ENV: 'production' },
    },
  ],
}

46-3

纯静态站点有两种做法：

  1. nuxt generate：SSG，构建时把路由预渲染成 HTML。还会生成 /200.html、/404.html 回退页，供客户端路由或 404 兜底。
  2. ssr: false：纯客户端 SPA，产物是空壳 HTML + JS 包。会丢掉大部分 SEO 好处，不推荐，除非页面完全不需要 SEO（用 <ClientOnly> 包裹不可 SSR 的部分更合适）。
export default defineNuxtConfig({
  ssr: false,
})
Tip

用 nuxt build + routeRules 选择性预渲染时，记得显式把回退页也预渲染：routeRules: { '/200.html': { prerender: true } }。nuxt generate 会自动生成这两个文件。

预渲染路由还会带 _payload.json，客户端导航时直接复用，不用重发请求。

46-4

各大云厂商都有现成 preset，配置极少。可以在 nuxt.config.ts 指定：

export default defineNuxtConfig({
  nitro: {
    preset: 'node-server',
  },
})

或用环境变量（构建时）：

NITRO_PRESET=vercel nuxt build

常见 preset 举例（具体以 Nitro 部署文档为准）：

  • vercel：Vercel
  • netlify：Netlify
  • cloudflare_pages / cloudflare_worker：Cloudflare
  • node-server：任意 Node 托管
  • bun：Bun 运行时
Note

多数平台「零配置」即可部署：推送代码后平台自动识别 Nuxt 并选用对应 preset。需要精细控制时再手动写 preset。

46-5

如果你的站前面挂了 Cloudflare，记得在控制台关掉两项，否则它可能往页面里注入脚本，导致 Nuxt 重复渲染或 hydration 报错：

  1. Speed > Settings > Content Optimization：关闭 “Rocket Loader™”
  2. Security > Settings：关闭 “Email Address Obfuscation”
Warning

Cloudflare 面板的选项位置偶尔会挪动，找不到就去搜索框搜关键字。开着这两项，生产环境可能出现莫名其妙的 hydration 警告。

46-6

  • 需要 SSR、有服务端逻辑、用户量中等 → Node 服务器（VPS + PM2，或任意 Node 托管）。
  • 内容站、博客、文档，更新不频繁 → 静态托管（最省心、最便宜）。
  • 想弹性扩缩、免运维 → Vercel/Netlify/Cloudflare 等 serverless/edge。
  • 一套代码里不同页面用不同策略 → 配合 routeRules（见第 43 章混合渲染）。
Tip

不确定选哪个？新手首选 Vercel 或 Netlify：推送即部署、自带预览环境、对 Nuxt 支持好，几乎不用配。等业务复杂了再考虑自托管 Node。

46-7

Nuxt 3 与 Nuxt 4 的部署体系一致，都靠 Nitro preset。差异仅在构建产物的源码路径（Nuxt 4 下 app/），.output/ 的结构与部署方式双方相同。

46-8

部署离不开环境变量。Nuxt 用 runtimeConfig 读取它们，但「在哪设」因环境不同：

  • 本地开发：写在 .env 文件，nuxt dev 自动加载。
  • CI / 构建时：在流水线里 export NITRO_PRESET=vercel 之类，构建产物会带上。
  • 生产运行时：在托管平台的环境变量面板填（Vercel/Netlify 都有），或 NODE_ENV=production PORT=3000 node .output/server/index.mjs 这样启动时传。

注意区分 runtimeConfig（服务端 + 可含密钥）和 runtimeConfig.public（会打进客户端包、浏览器可见）。密钥永远放前者，别把数据库密码写进 public。

46-9

拿不准时，用这张表粗选：

  • 有 SSR、要服务端逻辑、想自己掌控 → 自托管 Node（VPS + PM2）。
  • 内容站/博客、更新少 → nuxt generate 静态托管，最便宜。
  • 想免运维、自动扩缩 → Vercel / Netlify / Cloudflare。
  • 同一应用里不同页不同策略 → 配合第 43 章 routeRules。
Tip

新手别一上来就折腾自托管服务器。先用 Vercel 把项目跑起来，等业务真需要再迁。迁移成本主要在环境变量和预设，代码基本不动。
部署上去不等于完事。上线后第一件事是验证：打开页面看 HTML 源码里有没有正确的 <title> 和 SSR 内容（确认 SSR 真的在跑，而不是退化成空壳）；再测一下带参数的路由、404 页、静态资源是不是都正常。如果新版本有问题，Node 部署可以用 PM2 的 pm2 rollback 回退到上一个实例；云平台（Vercel/Netlify）每次部署都有独立 URL 和历史记录，点一下就能回滚，这也是它们省心的地方。

Tip

上线前在本地先 npx nuxt build && node .output/server/index.mjs 跑一遍产物，很多「部署才出现」的问题（路径、环境变量缺失）在本地就能提前暴露，比等到线上再排查快得多。

46-10

部署三形态：Node 服务器（默认）、静态托管（generate）、云平台 preset（vercel/netlify/cloudflare 等）。记得设 NODE_ENV=production，Cloudflare 关掉 Rocket Loader。下一章我们盘点常用的官方/社区模块。

46-7 部署后的运维要点

部署只是上线的第一步，后续的运维同样重要。首先，确保日志系统正常工作。服务端日志能帮你追踪请求链路、排查错误、分析性能瓶颈。Nuxt 的 Nitro 引擎支持多种日志格式，根据部署平台选择合适的输出方式。

其次，配置健康检查端点。大多数部署平台会定期访问一个健康检查 URL，确认应用还在正常运行。在 Nitro 里添加一个简单的 /health 路由，返回服务状态，能让平台及时发现并重启异常实例。

最后，制定回滚方案。如果新版本出现严重问题，能够快速回滚到上一个稳定版本。大多数部署平台支持一键回滚。如果是自建服务器，保留最近几个版本的产物目录，方便快速切换。

46-8 容器化部署方案

Docker 是目前最主流的容器化部署方案。把 Nuxt 应用打包成 Docker 镜像，可以确保在任何环境里都以相同的方式运行，避免”在我机器上能跑”的问题。

Nuxt 的 Nitro 引擎对容器化部署有天然的支持。构建产物是一个独立的 Node.js 应用，只需要一个基础的 Node.js 镜像就能运行。编写 Dockerfile 时，采用多阶段构建：第一阶段安装依赖并构建，第二阶段只复制产物到轻量级镜像里。这样最终的镜像体积很小，启动也更快。

部署时，用 Docker Compose 编排应用和它依赖的服务（如数据库、缓存）。生产环境下，配合 Kubernetes 或 Docker Swarm 做容器编排，实现自动扩缩容、滚动更新、故障恢复。

上一篇
测试：@nuxt/test-utils
下一篇
模块生态速览