Vite 集成

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

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

#Nitro 作为 Vite 插件

将插件添加到 Vite 配置中：

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：使用任意部署预设将客户端和服务器一起构建到单个可部署的 .output/ 目录中
vite preview：通过 Nitro 在本地提供生产构建，包括静态资源和 WebSocket 支持

Tip

请按照快速开始中的步骤，将 Nitro 添加到现有的 Vite 项目中

Note

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

#前端框架

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

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 入口。

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

#使用 Vite 配置 Nitro

Nitro 配置可以位于以下三个位置，并且都接受相同的选项：

nitro.config.ts 文件（大多数项目推荐）

Vite 配置中的 nitro 键

传递给 nitro() 的内联插件选项

import { defineConfig } from "nitro";

export default defineConfig({
  serverDir: "./server",
});

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

Vite 插件还可以通过在插件对象上暴露 nitro 键（一个 Nitro 模块），以编程方式扩展 Nitro。请参阅 Vite Nitro 插件示例。

#实验性插件选项

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

启用 ?assets 导入，以从入口点收集 CSS 和 JS 资源（默认值：true）

当仅服务器模块发生变化时重新加载服务器（以及浏览器）（默认值：true）

注册其他服务器环境，使其成为可获取的服务

#构建器

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

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

#构建器的选择方式

构建器按以下顺序解析：

Nitro 配置中的 builder 选项

NITRO_BUILDER 环境变量

自动检测：如果已安装 vite，且你的 vite.config 使用了 nitro() 插件，则使用 vite 构建器

否则，Nitro 默认为 rolldown

nitro.config.ts

import { defineConfig } from "nitro";

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

或者无需修改配置文件：

NITRO_BUILDER=rollup nitro build

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

#应选择哪个构建器

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

#自定义打包器

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

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 约定加载 .env、.env.local 以及特定模式的变体（.env.[mode]、.env.[mode].local）。现有环境变量的优先级高于 .env 值
Vite 环境：Nitro 使用 Vite 环境 API，并注册 client 和 nitro 环境（存在 SSR 入口时还会注册 ssr）。你可以通过 Vite 配置中的 environments.client.build.rollupOptions.input 配置客户端入口点，如 SSR 示例所示。

Edit this page

Previous CLI Next 服务器工具

On this page