Nitro v3.0.260903-beta 发布：安全加固、缓存默认值变更与依赖大升级

译注：本文译自 Nitro 官方 GitHub Release 页面，原文链接见文末。该版本为 beta 测试版，发布日期为 2026-09-03。

Nitro 发布 v3.0.260903-beta 版本。本次更新聚焦安全加固、缺陷修复、可观测性提升以及更可靠的开发体验。官方表示，许多改进来自一批核心依赖的大版本升级（h3、srvx、rou3、ocache、db0、env-runner、unctx 与 unwasm），以及 Nitro 为适配这些升级所做的工作。

路由与路由规则

Nitro 迁移到 h3 的新路由规则引擎，底层由 rou3 v0.9 支撑。规则基于规范化路径（canonical path）匹配，同级路由按具体程度排序。GET 路由现在会自动响应 HEAD 请求。

新增 cors 规则，取代手动配置 CORS 的方式：

{ "/api/**": { cors: true } }

原有的 basicAuth 路由规则被中间件取代，迁移方式见下文。

缓存：默认值发生变更

defineCachedHandler、defineCachedFunction 与 cache 路由规则现在运行在 ocache v0.3（此前为 0.1）之上，带来更安全的默认值、有界内存以及若干新能力。官方特别提醒：请检查你的缓存配置，默认值已发生变化。

主要变更包括：

swr 默认值改为 false，过期条目会在返回前刷新；如需后台重新验证，需显式设置 swr: true。
默认忽略查询参数，需设置 allowQuery: true 或列出应影响缓存键的参数。
除非列入 allowCookies，缓存请求与响应中的 Cookie 会被移除；包含 Set-Cookie 的响应不会被缓存。
GET 与 HEAD 现在使用独立的缓存条目。
缓存键现在包含请求 authority，未声明的请求头对处理器不可见。
缓存解析新增 30 秒超时（maxResolveTime），内存存储按字节数限制。

数据库与 WebSocket

数据库方面，Nitro 改用 db0 v0.4。数据库客户端库需显式传递给连接器，Nitro 会为已配置的连接器处理此事，并提示安装缺失的包。该版本新增 neon、prisma 与 libsql-core 连接器、Kysely 集成、数据库 capabilities 元数据以及 tracing channel 支持。

WebSocket 支持升级到 crossws 0.4.12（此前为 0.4.6），新增能力包括：用于检测半开连接的通用 idleTimeout、应用层 ping/pong 钩子与 peer.ping()；背压相关的 peer.bufferedAmount 与可选的子协议协商；以及用于跨实例共享频道的同步 backplane，并支持鉴权与上下文。

可观测性与追踪

原生平台追踪：Nitro 可向 Vercel session traces 与 Cloudflare Workers Observability 发送 span，无需打包 OpenTelemetry SDK。
内置追踪日志器：启用 tracingChannel 与 experimental.tracingLogger，即可在开发与生产环境记录已完成的 h3、srvx、unstorage、db0 等 span，无需额外依赖。

安全加固

h3 经历了多轮安全加固审计，覆盖路径规范化、转发头、Host 头处理、Cookie、CORS、basic auth、JSON-RPC 与会话密封。

开发任务端点（/_nitro/tasks 与 /_nitro/tasks/:name）现在仅接受本地请求，防止可访问开发服务器的远程客户端列出或调用任务。缓存响应默认不再重放 Cookie。静态文件响应也得到增强：支持 ETag 与 Last-Modified 条件请求、字节范围、可选的 Cache-Control，并加强了路径穿越防护。

性能与开发体验

别名解析、开发环境 sourcemap、请求中间件与日志均有改进。开发 worker 重载被串行化并正确等待，过期的模块缓存会被清理，Vite 别名按正确顺序生效，base path 得到尊重，?import 请求仍由 Vite 处理。静态预设不再生成不必要的服务端 bundle。

此外，服务端 bundle 中支持以 bytes 或 text 形式导入任意文件：

import logo from "./logo.png" with { type: "bytes" }; // Uint8Array
import readme from "./README.md" with { type: "text" }; // string

不再有 peer 依赖

Nitro 不再有任何 peer 依赖。需要额外包的功能（构建器、预设、存储驱动、数据库连接器）会从用户项目中解析，并提示安装缺失项；在 CI 中缺失的包会自动安装。已安装所需包的现有项目无需改动。Nitro 还会校验所发现包的版本，并在超出支持范围时发出警告。支持的构建器为 vite@^7 || ^8、rollup@^4 与 rolldown@>=1.0.0。

同时，多个包被彻底移除：tsconfck（由 get-tsconfig 替代）、magic-string、uncrypto、serve-placeholder、edge-runtime、@types/http-proxy 与 @types/node-fetch。ofetch 不再是运行时依赖，rou3 则从间接依赖变为直接依赖。

预设更新

Cloudflare：本地开发直接使用 Miniflare/workerd，绑定可在 request event 上获取；首次需要时 Nitro 会提示安装 miniflare。
Vercel：设置 vercel.immutableStaticFiles: true 可输出带内容哈希的静态文件并启用不可变缓存。
Netlify Edge：保持动态导入的惰性，减少懒加载处理器与延迟 WASM 初始化的冷启动开销。

迁移事项

路由：用中间件替换 basicAuth 路由规则。

import { defineHandler } from "nitro";
import { basicAuth } from "nitro/h3";

export default defineHandler({
  middleware: [basicAuth({ username: "admin", password: "supersecret" })],
  handler: (event) => `Hello, ${event.context.basicAuth?.username}!`,
});

如需保护多个路由，可注册路由级中间件，或将其放入 middleware/ 目录。需要时使用新的 cors 规则：{ "/api/**": { cors: true } }。类型方面，NitroRouteConfig 与 NitroRouteRules 已成为 RouteRuleConfig 与 NormalizedRouteRules 的废弃别名，旧名称仍从 nitro/types 导出。

缓存配置：从 ocache 0.1 升级到 0.3 引入了更安全的默认值，具体变更见上文「缓存」小节，详细说明可参考 ocache 迁移指南。

主要依赖升级

包	原版本	新版本
h3	2.0.1-rc.22	^2.0.1-rc.29
srvx	^0.11.16	^0.12.7
rou3	^0.8.1	^0.9.2
db0	^0.3.4	^0.4.0
env-runner	^0.1.12	^0.2.0
ocache	^0.1.5	^0.3.0
unctx	^2.5.0	^3.0.1
unwasm	^0.5.3	^0.6.0

其中 h3 带来新路由规则引擎、QUERY 方法支持、GET 路由自动匹配 HEAD、会话默认 SameSite=Lax 与 PBKDF2 密封迭代提升至 8192 等变更；srvx 增强了静态文件安全与条件请求支持；rou3 新增路由模式重叠工具与 regExpToRoute()；unctx 默认使用内置 AsyncLocalStorage 并将转换迁移到 oxc；unwasm 以内置 WASM 解析器替换 webassemblyjs，减少依赖并减轻安装体积。

原文链接

https://github.com/nitrojs/nitro/releases/tag/v3.0.260903-beta

Nitro v3.0.260903-beta 发布：安全加固、缓存默认值变更与依赖大升级 ​

路由与路由规则 ​

缓存：默认值发生变更 ​

数据库与 WebSocket ​

可观测性与追踪 ​

安全加固 ​

性能与开发体验 ​

不再有 peer 依赖 ​

预设更新 ​

迁移事项 ​

主要依赖升级 ​

原文链接 ​

相关文章