构建、生成与预览
本教程共 50 篇 · 第 6 篇 · 更新于 2026-08-08 · 约 6 分钟阅读
本节目标：分清
build、generate、preview三条命令分别做什么，明白「打包」「预渲染」「本地预览」的区别，以及它们产出物适合怎么部署。
开发时你跑的是 dev，那是给开发者用的。真正要把应用交给用户，得先「构建」出一份优化过的产物。Nuxt 提供几条不同的命令，对应不同的上线方式。这章把它们讲清楚，避免你用错命令。
6-1
build 是把整个 Nuxt 应用（前端 + 服务端）编译、压缩、优化，产出一份能部署到服务器的完整产物。
# npm
npm run build
# pnpm
pnpm build执行后，项目里会多出 .output/ 目录，里面就是打包结果。在 Node 服务器上，这样启动它：
NODE_ENV=production node .output/server/index.mjs它默认监听 3000 端口。你也可以用环境变量改端口和地址：
# 改用 8080 端口
NITRO_PORT=8080 node .output/server/index.mjsWarning生产启动务必带上
NODE_ENV=production。否则像 Vue Router 这类依赖不会剥离开发期警告，日志会被一堆[Vue Router warn]刷屏，影响性能和排查。
build 的适用场景：你要部署到一个 Node 服务器，并且应用需要服务端能力（SSR、API 接口）。这是最「全功能」的产物。
6-2
如果你的站点内容不常变（比如官网、文档、博客），可以把它在构建时一次性渲染成静态 HTML，直接丢到任意静态托管（CDN、GitHub Pages、对象存储）上，连服务器都不用养。
npm run generategenerate 内部走的是 SSG（静态站点生成），默认会为每条路由生成对应的 .html 文件，外加两个回退页：
200.html：单页应用回退页，用于客户端路由处理未匹配路径。404.html：未找到页面的回退。
还会生成 _payload.json，保存构建时抓取的数据，供客户端导航时复用。
Note
generate是纯静态产物，里面不含服务端。也就是说，生成出来的文件里没有后端接口——如果你的页面依赖server/api/，用generate就调不到了。需要服务端功能请用build。
6-3
一句话概括：要服务端能力（SSR/Api）选 build；内容固定、追求极速和零服务器成本选 generate。
| 命令 | 产物形态 | 是否需要服务器 | 适合场景 |
|---|---|---|---|
build | .output/ 含服务端 | 是（Node/Serverless） | 动态站点、有后端 API |
generate | 静态 .html + 资源 | 否（静态托管即可） | 官网、博客、文档 |
Tip还有个折中叫「混合渲染」：用
routeRules给不同路由指定不同策略（首页预渲染、管理后台仅客户端）。这部分留到第 43 章讲，现在先记住有这个能力。
6-4
构建或生成之后，你想在本地先看看「上线后到底是什么样」，而不是再开一个 dev。这时用 preview：
npm run previewpreview 会启动一个服务器，加载你刚刚 build 或 generate 出来的产物，模拟真实上线环境。它和 dev 的关键区别是：preview 跑的是优化后的生产代码，没有 HMR，也没有错误覆盖层，更接近用户真正看到的样子。
Warning不要拿
preview当开发服务器用——它没有热更新，改了代码也不会自动刷新。它只用于「构建完确认效果」。日常开发请继续用dev。
6-5
build 产出的 .output/ 很轻量，可以部署到很多平台。Nitro 用「preset（预设）」来适配不同运行环境。你可以在 nuxt.config.ts 里指定：
export default defineNuxtConfig({
nitro: {
preset: 'node-server',
},
})或者在构建时通过环境变量指定：
NITRO_PRESET=node-server npm run build常见 preset 涵盖 Node 服务器、各种 Serverless、边缘（Cloudflare Workers、Vercel Edge、Netlify Edge）等。Nuxt 强调「部署到任何地方，包括边缘」，靠的就是这层 preset 抽象。
Note不同平台的具体部署步骤各有差异，第 46 章会展开。现在你只需理解：本地用
build/generate产出，用preview自检，最后把产物交给对应平台的 preset 部署。
6-6
build 和 generate 不是一键魔法，背后大致分几步，知道流程有助于排查慢或报错：
- 准备：Nuxt 先重新生成
.nuxt/里的类型和临时文件，确保代码和类型同步。 - 客户端打包：用 Vite 把
app/下的代码、组件、样式打包成浏览器能跑的 JS/CSS，并做代码分割、压缩。 - 服务端打包：用 Nitro 把
server/下的代码编译成一个独立的可部署服务（.output/server）。 - 产物整理：把静态资源、HTML 模板、服务端入口按 preset 要求的格式排好，放进
.output/。
Note构建比
dev慢很多是正常的——它在做压缩、tree-shaking、类型检查（若开了）这些dev跳过的重活。一个中型项目构建几十秒到几分钟都常见，别以为卡死了。
6-7
- 产物体积过大：先想清楚到底要不要
generate全站。内容固定的页面才适合静态化；动态数据多的页面用build+ SSR 更合适。 - 构建中途报错：多半是某段代码在严格模式下过不了（类型、未定义变量）。读终端报错，定位到具体文件行号，比无头苍蝇乱改高效。
- 怀疑缓存作怪：删掉
.nuxt/和.output/两个目录再构建一次，能排除旧产物的干扰。
Tip
preview跑的是build/generate的产物，所以「dev 正常、preview 报错」通常说明问题藏在构建优化阶段（比如某个只在生产才触发的压缩/兼容问题），顺着产物方向查。
6-8
开发用 dev，上线前用 build（全功能服务端应用）或 generate（纯静态站点），产完用 preview 在本地模拟真实环境自检。三条命令职责分明，别混用。下一章我们深入 nuxt.config.ts，看怎么通过配置定制这些行为。
6-8 构建产物的结构
执行 nuxt build 后，产物会输出到 .output/ 目录。了解这个目录的结构有助于你排查部署问题。.output/server/ 里是服务端代码，.output/public/ 里是静态资源（JS、CSS、图片等）。部署时，你需要确保服务器能正确访问这两个目录。
对于 SSR 模式，服务器需要同时处理 .output/server/ 里的 Node.js 服务和 .output/public/ 里的静态文件。大多数部署平台（Vercel、Netlify 等）会自动识别 Nuxt 的产物结构并正确配置。如果是自建服务器，你需要根据平台文档手动配置反向代理和静态文件服务。
构建过程中如果遇到报错，最常见的原因是 TypeScript 类型错误、依赖缺失、或者某个组件引用了不存在的模块。先按报错信息定位文件，逐一修复后重新构建。