---
title: "部署项目"
description: "了解如何将你的 Nuxt 应用部署到任意托管提供商。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/getting-started/deployment"
---
# 部署项目

> 了解如何将你的 Nuxt 应用部署到任意托管提供商。

Nuxt 应用可以部署在 Node.js 服务器上、预渲染用于静态托管，或部署到无服务器或边缘（CDN）环境。

<tip>

如果你在寻找支持 Nuxt 的云提供商列表，请参阅 [托管提供商](https://nuxt.zhcndoc.com/deploy) 部分。

</tip>

## Node.js 服务器

使用 Nitro 的 Node.js 服务器预设，了解如何在任意 Node 托管环境中部署。

- **默认输出格式**（如果未指定或自动检测）<br />
- 仅加载渲染请求所需的 chunk，以优化冷启动时间<br />
- 适用于将 Nuxt 应用部署到任何 Node.js 托管环境

### 入口点

当使用 Node 服务器预设运行 `nuxt build` 时，结果将是一个可启动的 Node 服务器入口点。

```bash [Terminal]
NODE_ENV=production node .output/server/index.mjs
```

这将启动你的生产 Nuxt 服务器，默认监听端口 3000。

<important>

运行服务器时请设置 `NODE_ENV=production`。某些依赖项（尤其是 Vue Router）只有在设置了该值时才会去除仅开发环境下的警告，因此如果不设置，它可能会在你的日志中充斥诸如 `[Vue Router warn]: No match found for location with path …` 之类的消息，尤其是在未匹配路由上。

</important>

它会遵循以下运行时环境变量：

- `NITRO_PORT` 或 `PORT`（默认 `3000`）
- `NITRO_HOST` 或 `HOST`（默认 `'0.0.0.0'`）
- `NITRO_SSL_CERT` 和 `NITRO_SSL_KEY` - 如果两者都存在，则以 HTTPS 模式启动服务器。在绝大多数情况下，除了用于测试外不建议直接使用，Nitro 服务器应当运行在像 nginx 或 Cloudflare 这样的反向代理之后，由它们来终止 SSL。

### 在多个路径提供相同的构建版本

对于常规的子路径部署，请设置 [`app.baseURL`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#baseurl) 或 `NUXT_APP_BASE_URL` 环境变量。

如果反向代理有意在多个公共路径上公开同一个渲染页面，Nuxt 可能会在 hydration 期间将浏览器 URL 替换为用于服务器渲染的路径。你可以在服务器插件中从 payload 中移除渲染路径，以保留浏览器 URL：

```ts [app/plugins/preserve-proxy-url.server.ts]
export default defineNuxtPlugin((nuxtApp) => {
  delete nuxtApp.payload.path
})
```

仅当代理已经处理每个公共路径的资源和路由时，才使用此方法。移除渲染路径后，Nuxt 将无法纠正请求 URL 与服务器渲染路由之间真实存在的不匹配。

### PM2

[PM2](https://pm2.keymetrics.io/)（进程管理器 2）是一个快速且简单的解决方案，用于在你的服务器或虚拟机上托管 Nuxt 应用。

要使用 `pm2`，请使用 `ecosystem.config.cjs`：

```ts [ecosystem.config.cjs]
module.exports = {
  apps: [
    {
      name: 'NuxtAppName',
      port: '3000',
      exec_mode: 'cluster',
      instances: 'max',
      script: './.output/server/index.mjs',
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
}
```

### 集群模式

你可以使用 `NITRO_PRESET=node_cluster` 来利用 Node.js [cluster](https://nodejs.org/dist/latest/docs/api/cluster.html) 模块实现多进程性能。

默认情况下，工作负载会使用轮询（round robin）策略分配给各个 worker。

### 了解更多

<read-more to="https://nitro.zhcndoc.com/deploy/runtimes/node" title="关于 node-server 预设 的 Nitro 文档">



</read-more>

<video-accordion title="观看 Daniel Roe 的相关短视频" video-id="0x1H6K5yOfs">



</video-accordion>

## 静态托管

将 Nuxt 应用部署到任意静态托管服务有两种方式：

- 使用 `ssr: true` 进行静态站点生成（SSG），在构建时预渲染应用的路由。（运行 `nuxt generate` 时，这是默认行为。）它还会生成 `/200.html` 和 `/404.html` 单页应用回退页面，这些页面可以在客户端渲染动态路由或 404 错误（不过你可能需要在静态托管服务上进行相应配置）。请参阅[什么是 200.html 和 404.html？](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/rendering#what-are-200html-and-404html)。
- 或者，你也可以使用 `ssr: false` 预渲染站点（静态单页应用）。这将生成 HTML 页面，其中包含一个空的 `<div id="__nuxt"></div>`，Vue 应用通常会在此处渲染。这样会失去预渲染站点带来的许多 SEO 优势，因此建议改用 [`<ClientOnly>`](https://nuxt.zhcndoc.com/docs/4.x/api/components/client-only) 包裹无法进行服务器渲染的站点部分（如果有）。

预渲染的路由还会生成 `_payload.json` 文件，其中包含构建时捕获的数据，Nuxt 会在客户端导航期间重复使用这些数据。了解有关 [payload 提取](https://nuxt.zhcndoc.com/docs/4.x/getting-started/prerendering#payload-extraction)的更多信息。

### 静态回退页面

Nuxt 可以为静态主机生成两个回退页面：

- `200.html` 是单页应用回退页面。当你希望由客户端路由处理 URL 时，请配置你的主机在未匹配路由时提供该页面。
- `404.html` 是未找到回退页面。请将你的主机配置为在应保持 404 状态的路由上提供该页面。

`nuxt generate` 和 `nuxt build --prerender` 会自动生成这些文件。如果你使用带路由规则的 `nuxt build` 来预渲染选定路由，请显式添加回退页面：

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  routeRules: {
    '/200.html': { prerender: true },
  },
})
```

默认情况下，这两个回退页面都是空壳。设置 [`experimental.prerenderErrorPages`](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/rendering#server-rendering-the-error-page)，即可在构建时将你的 `error.vue` 服务器渲染到 `404.html` 中。

某些提供商使用 `200.html`，某些使用 `404.html`，还有一些允许你同时配置两者。部署后请检查你的托管提供商的静态回退或重写设置。

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/getting-started/prerendering" title="Nuxt 预渲染">



</read-more>

### 仅客户端渲染

如果你不想预渲染路由，另一种使用静态托管的方法是在 `nuxt.config` 文件中将 `ssr` 属性设置为 `false`。然后 `nuxt generate` 命令会输出一个 `.output/public/index.html` 入口点和 JavaScript 包，就像经典的客户端 Vue.js 应用一样。

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  ssr: false,
})
```

## 托管提供商

Nuxt 可以以最少的配置部署到多个云提供商：

<read-more to="https://nuxt.zhcndoc.com/deploy">



</read-more>

## 预设

除了 Node.js 服务器和静态托管服务之外，Nuxt 项目还可以通过多个经过充分测试的预设，以最少的配置进行部署。

你可以在 [`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt-config) 文件中显式设置所需的预设：

```ts [nuxt.config.ts]twoslash
// @errors: 2353
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server',
  },
})
```

... 或在运行 `nuxt build` 时使用 `NITRO_PRESET` 环境变量：

```bash [Terminal]
NITRO_PRESET=node-server nuxt build
```

🔎 查阅 [Nitro 部署](https://nitro.zhcndoc.com/deploy) 以了解所有可能的部署预设和提供商。

## CDN 代理

在大多数情况下，Nuxt 可以与那些并非由 Nuxt 本身生成或创建的第三方内容一起工作。但有时这类内容可能会导致问题，尤其是 Cloudflare 的“压缩和安全选项”。

因此，你应确保在 Cloudflare 中取消选中／禁用以下选项。否则，不必要的重新渲染或 hydration 错误可能会影响你的生产应用。

1. 速度 > 设置 > 内容优化 > 禁用“Rocket Loader™”
2. 安全 > 设置 > 禁用“电子邮件地址混淆”

有了这些设置，你就可以确保 Cloudflare 不会将脚本注入到你的 Nuxt 应用中，进而导致不想要的副作用。

<tip>

它们在 Cloudflare 仪表盘中的位置有时会变化，所以别犹豫，多看看周边的设置。

</tip>


## Sitemap

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