# Vite 集成

> 使用 Nitro 作为 Vite 插件构建全栈应用，并选择用于打包服务器的构建器

Nitro 以插件形式与 [Vite](https://vite.dev) 集成。将其添加到 Vite 项目后，除了前端之外，还能获得完整的服务器功能：API 路由、服务器端渲染，以及可部署到任意位置的生产构建。

## Nitro 作为 Vite 插件

将插件添加到 Vite 配置中：

```ts [vite.config.ts]
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [nitro()],
});
```

启用插件后，所有操作都使用 Vite CLI：

- **`vite dev`**：为前端和后端提供一个开发服务器。Nitro 提供服务器路由和资源，而 Vite 处理客户端模块。服务器代码在隔离的 worker 中运行，并在服务器文件发生变化时自动重新加载；客户端代码则继续使用 Vite 的热模块替换（HMR）
- **`vite build`**：使用任意[部署预设](/deploy)将客户端和服务器一起构建到单个可部署的 `.output/` 目录中
- **`vite preview`**：通过 Nitro 在本地提供生产构建，包括静态资源和 WebSocket 支持

::tip
请按照[快速开始](/docs/quick-start#add-to-a-vite-project)中的步骤，将 Nitro 添加到现有的 Vite 项目中
::

::note
使用 Vite 插件时，优先使用 `vite dev` 而不是 `nitro dev`；Nitro CLI 开发服务器不支持 Vite 构建器。`nitro build` 可以正常工作，并会在底层运行 Vite 构建
::

## 前端框架

Nitro 插件可以与其他 Vite 插件组合使用，因此你可以使用偏好的前端框架，通过客户端水合实现服务器端渲染：

```ts [vite.config.ts]
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [nitro(), react()],
});
```

Nitro 会自动检测名为 `entry-server.(ts|js|tsx|jsx|mjs)` 的文件（位于项目根目录、`app/`、`src/` 或服务器目录中），并将其用作 SSR 入口。

无需逐一重新解释每种设置，请参阅以下可运行示例：

- [使用 React 的 SSR](/examples/vite-ssr-react)
- [使用 Vue Router 的 SSR](/examples/vite-ssr-vue-router)
- [使用 Solid 的 SSR](/examples/vite-ssr-solid)
- [使用 Preact 的 SSR](/examples/vite-ssr-preact)
- [React Server Components](/examples/vite-rsc)
- [使用纯 HTML 的 SSR](/examples/vite-ssr-html)

::read-more{to="/docs/renderer"}
请在 [renderer](/docs/renderer) 和[服务器入口](/docs/server-entry)指南中进一步了解未匹配路由的渲染方式
::

## 使用 Vite 配置 Nitro

Nitro 配置可以位于以下三个位置，并且都接受相同的[选项](/config)：

1. `nitro.config.ts` 文件（大多数项目推荐）
2. Vite 配置中的 `nitro` 键
3. 传递给 `nitro()` 的内联插件选项

::code-group
```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  serverDir: "./server",
});
```
```ts [vite.config.ts (nitro key)]
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [nitro()],
  nitro: {
    serverDir: "./server",
  },
});
```
```ts [vite.config.ts (inline)]
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [
    nitro({
      serverDir: "./server",
    }),
  ],
});
```
::

内联插件选项的优先级高于 Vite 配置中的 `nitro` 键，而这两者的优先级都高于 `nitro.config.ts`。`dev` 模式和 `rootDir` 会从 Vite 推断，无法覆盖。

Vite 插件还可以通过在插件对象上暴露 `nitro` 键（一个 [Nitro 模块](/docs/modules)），以编程方式扩展 Nitro。请参阅 [Vite Nitro 插件示例](/examples/vite-nitro-plugin)。

### 实验性插件选项

该插件还接受 `experimental.vite` 下的 Vite 专用标志：

::field{name="assetsImport" type="boolean"}
启用 `?assets` 导入，以从入口点收集 CSS 和 JS 资源（默认值：`true`）
::

::field{name="serverReload" type="boolean"}
当仅服务器模块发生变化时重新加载服务器（以及浏览器）（默认值：`true`）
::

::field{name="services" type="Record<string, { entry: string }>"}
注册其他服务器环境，使其成为可获取的服务
::

## 构建器

Nitro 可以使用以下三种构建器之一打包服务器：

| 构建器 | 描述 |
| --- | --- |
| `rolldown` | 默认构建器。基于 Rust 的打包器，随 Nitro 一起提供，无需额外安装 |
| `rollup` | 久经考验且拥有成熟插件生态系统的打包器。需要安装 `rollup` |
| `vite` | 通过 Vite 插件进行全栈构建。需要安装 `vite` |

### 构建器的选择方式

构建器按以下顺序解析：

1. Nitro 配置中的 `builder` 选项
2. `NITRO_BUILDER` 环境变量
3. 自动检测：如果已安装 `vite`，且你的 `vite.config` 使用了 `nitro()` 插件，则使用 `vite` 构建器
4. 否则，Nitro 默认为 `rolldown`

```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  builder: "rollup",
});
```

或者无需修改配置文件：

```bash
NITRO_BUILDER=rollup nitro build
```

如果你明确选择了 `rollup` 或 `vite`，但未安装相应的软件包，Nitro 会提示将其作为开发依赖安装。

### 应选择哪个构建器

- 对于独立服务器和 API，选择 **`rolldown`**。它是速度最快的选项，开箱即用
- 如果依赖 Rollup 专用插件，或需要最大的生态系统兼容性，请选择 **`rollup`**
- 只要前端使用 Vite 构建，就使用 **`vite`**（通常通过自动检测）。它是唯一能将客户端和服务器一起打包的构建器

### 自定义打包器

对于高级场景，你可以通过 `rollupConfig` 或 `rolldownConfig`，直接向底层打包器传递额外配置：

```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  rolldownConfig: {
    // Extra Rolldown options and plugins
  },
  rollupConfig: {
    // Extra Rollup options and plugins
  },
});
```

每个选项仅应用于与其匹配的构建器。使用 `vite` 构建器时，根据 Vite 运行在 Rolldown（`rolldown-vite`）还是 Rollup 上，两者都会合并到服务器打包配置中。

::warning
这些选项属于应急手段。在可用时优先使用 Nitro 内置选项，因为底层打包器覆盖配置可能会在不同构建器之间失效
::

## 需要了解的事项

- **服务器重新加载而非 HMR**：仅服务器模块发生变化时，会触发服务器重新加载（以及浏览器刷新），而不是热模块替换。在客户端和服务器之间共享的模块仍会保留正常的 Vite HMR
- **开发服务器端口**：端口依次从 `PORT` 环境变量、Vite 的 `server.port`，以及 Nitro 的 `devServer.port` 中解析（默认值：`3000`）
- **环境文件**：在开发和构建过程中，Nitro 都会遵循 [Vite 约定](https://vite.dev/guide/env-and-mode#env-files)加载 `.env`、`.env.local` 以及特定模式的变体（`.env.[mode]`、`.env.[mode].local`）。现有环境变量的优先级高于 `.env` 值
- **Vite 环境**：Nitro 使用 [Vite 环境 API](https://vite.dev/guide/api-environment)，并注册 `client` 和 `nitro` 环境（存在 SSR 入口时还会注册 `ssr`）。你可以通过 Vite 配置中的 `environments.client.build.rollupOptions.input` 配置客户端入口点，如 [SSR 示例](/examples/vite-ssr-react)所示。