迁移指南

这是一份关于从 Nitro 2 迁移到 3 的动态文档。在使用测试版期间，请定期查看。

Nitro v3 引入了有意的不向后兼容的更改。本指南帮助你从 Nitro v2 迁移。

`nitropack` 重命名为 `nitro`

NPM 包 nitropack (v2) 已重命名为 nitro (v3)。

迁移： 在 package.json 中将 nitropack 依赖更新为 nitro：

{
  "dependencies": {
--    "nitropack": "latest"
++    "nitro": "latest"
  }
}

{
  "dependencies": {
--    "nitropack": "latest"
++    "nitro": "npm:nitro-nightly"
  }
}

迁移： 搜索你的代码库，将所有 nitropack 实例重命名为 nitro：

-- import { defineNitroConfig } from "nitropack/config"
++ import { defineNitroConfig } from "nitro/config"

nitro/runtime

运行时工具已移至独立的 nitro/* 子路径导出。有关用法请参阅文档。

-- import { useStorage } from "nitropack/runtime/storage"
++ import { useStorage } from "nitro/storage"

最低支持的 Node.js 版本：20

Nitro 现在需要最低 Node.js 版本 20，因为 Node.js 18 将于 2025 年 4 月结束生命周期。

请升级到最新的 LTS 版本（>= 20）。

迁移：

使用 node --version 检查你的本地 Node.js 版本，并在必要时更新。
如果你使用 CI/CD 系统进行部署，请确保你的流水线正在运行 Node.js 20 或更高版本。
如果你的托管提供商管理 Node.js 运行时，请确保其设置为版本 20、22 或更高。

类型导入

Nitro 类型现在仅从 nitro/types 导出。

迁移： 从 nitro/types 而不是 nitro 导入类型：

-- import { NitroRuntimeConfig } from "nitropack"
++ import { NitroRuntimeConfig } from "nitro/types"

应用配置支持已移除

Nitro v2 支持捆绑的应用配置，允许在 app.config.ts 中定义配置，并通过 useAppConfig() 在运行时访问它们。

此功能已被移除。

迁移：

在你的 server 目录中使用常规的 .ts 文件并直接导入它。

预设更新

Nitro 预设已更新以兼容最新版本。

一些（旧版）预设已被移除或重命名。

旧预设	新预设
`node`	`node_middleware`（导出更改为 `middleware`）
`cloudflare`, `cloudflare_worker`, `cloudflare_module_legacy`	`cloudflare_module`
`deno-server-legacy`	`deno_server`（使用 Deno v2）
`netlify-builder`	`netlify` 或 `netlify_edge`
`vercel-edge`	`vercel`（启用 Fluid 计算）
`azure`, `azure_functions`	`azure_swa`
`firebase`	`firebase_app_hosting`
`iis`	`iis_handler`
`deno`	`deno_deploy`
`edgio`	已停止维护
`cli`	因缺乏使用而移除
`service_worker`	因不稳定而移除

Cloudflare 绑定访问

在 Nitro v2 中，可通过 event.context.cloudflare.env 访问 Cloudflare 环境变量和绑定。

在 Nitro v3 中，Cloudflare 运行时上下文已附加到请求的运行时对象上。

迁移：

-- const { cloudflare } = event.context
-- const binding = cloudflare.env.MY_BINDING
++ const { env } = event.req.runtime.cloudflare
++ const binding = env.MY_BINDING

更改的 nitro 子路径导入

Nitro v2 引入了多个子路径导出，其中一些已被移除或更新：

nitro/rollup、nitropack/core（使用 nitro/builder）
nitropack/runtime/*（使用 nitro/*）
nitropack/kit（已移除）
nitropack/presets（已移除）

实验性的 nitropack/kit 曾被引入，但现已移除。未来可能会推出独立的 Nitro Kit 包，目标更加明确。

迁移：

使用 nitro/types 中的 NitroModule 替代 kit 中的 defineNitroModule。
优先使用内置的 Nitro 预设（外部预设仅用于评估目的）。

H3 v2

Nitro v3 升级到 H3 v2，其中包含 API 更改。所有 H3 工具从 nitro/h3 导入。

Web 标准

H3 v2 基于 Web 标准原语（URL、Headers、Request 和 Response）重写。

仅在 Node.js 运行时中可访问 event.node.{req,res}。event.web 已重命名为 event.req（Web Request 的实例）。

响应处理

你应该始终显式地 return 响应体或 throw 一个错误：

-- import { send, sendRedirect, sendStream } from "nitro/h3"
-- send(event, value)
-- sendStream(event, stream)
-- sendRedirect(event, location, code)
++ import { redirect } from "nitro/h3"
++ return value
++ return stream
++ return redirect(event, location, code)

其他更改：

sendError(event, error) → throw createError(error)
sendNoContent(event) → return noContent(event)
sendProxy(event, target) → return proxy(event, target)

请求体

大多数 body 工具可以被原生的 event.req 方法替代：

-- import { readBody, readRawBody, readFormData } from "nitro/h3"
++ // 使用原生 Request 方法
++ const json = await event.req.json()
++ const text = await event.req.text()
++ const formData = await event.req.formData()
++ const stream = event.req.body

请求头

H3 现在使用标准 Web Headers。请求头的值始终是纯 string（没有 null、undefined 或 string[]）。

-- import { getHeader, setHeader, getResponseStatus } from "nitro/h3"
-- getHeader(event, "x-foo")
-- setHeader(event, "x-foo", "bar")
++ event.req.headers.get("x-foo")
++ event.res.headers.set("x-foo", "bar")
++ event.res.status // 替代 getResponseStatus(event)

处理器工具

-- import { eventHandler, defineEventHandler } from "nitro/h3"
++ import { defineHandler } from "nitro"

lazyEventHandler → defineLazyEventHandler
useBase → withBase

错误工具

-- import { createError, isError } from "nitro/h3"
++ import { HTTPError } from "nitro"
++ throw new HTTPError({ status: 404, message: "Not found" })
++ HTTPError.isError(error)

Node.js 工具

-- import { defineNodeListener, fromNodeMiddleware, toNodeListener } from "nitro/h3"
++ import { defineNodeHandler, fromNodeHandler, toNodeHandler } from "nitro/h3"

可选钩子

如果你之前曾在 Nitro 插件之外使用 useNitroApp().hooks，它可能是 undefined。使用新的 useNitroHooks() 来确保获得实例。

KV 存储

Nitro 提供了一个内置的存储层，可以抽象文件系统、数据库或任何其他数据源。

每日构建通道

Nitro 有一个每日构建发布通道，它会针对 main 分支的每一次提交自动发布，以便尝试最新的更改。