Nitro 请求生命周期与错误处理完全指南从 Request Hook 到服务器关闭【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro本篇技术指南以 Nitro 官方文档 docs/1.docs/50.lifecycle.md 为骨架深入讲解一个请求从进入 Nitro 到响应返回所经过的每一层处理环节以及错误处理与服务器关闭的完整机制。读者读完将掌握 Nitro 请求管道中各层级的执行顺序、如何在插件中挂载request/response/error/close运行时钩子、如何用HTTPError精确控制错误响应以及如何通过errorHandler/devErrorHandler定制生产与开发环境的错误输出。一、Nitro 的请求生命周期总览Nitro 是一个下一代服务器工具包其核心设计之一是请求可以被请求管道中任意一层拦截并终止无论是否携带响应。理解这些层级的执行顺序是编写可靠中间件、路由与错误处理代码的前提。一个传入请求按以下顺序依次经过各层任意一层都可以终止请求request钩子通过运行时插件注册Route rules路由规则来自routeRules配置静态资源处理public/目录作为第一个全局中间件全局中间件middleware/目录自动注册路由级中间件通过handlers配置的路由范围中间件路由处理器routes/目录服务器入口Server entry未匹配任何路由时兜底渲染器Renderer作为最后的兜底response钩子响应创建后、发送前执行下面逐层展开。二、第一层request钩子request是每个传入请求执行的第一段代码通过运行时插件注册import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(request, (event) { console.log(Incoming request on ${event.req.url}); }); });注意在request钩子内抛出的错误会被error钩子捕获而不会终止请求管道。这意味着你可以放心地在其中做日志、鉴权预检查等操作而不必担心意外中断请求。从源码看插件的初始化发生在 Nitro 应用首次创建时。在 src/runtime/internal/app.ts 中useNitroApp()会创建应用实例并调用initNitroPlugins(instance)L25-L28运行时插件正是通过这一步完成挂载随后nitroApp.hooks.hook(...)注册的钩子才会对每个请求生效。三、第二层Route rules 路由规则与请求匹配的 route rules来自 Nitro 配置在全局中间件之前执行。Route rules 以中间件形式运行其中大部分规则只修改响应而不会终止请求例如添加响应头、设置缓存策略等import { defineConfig } from nitro; export default defineConfig({ routeRules: { /**: { headers: { x-nitro: first } } } })关键细节匹配到的规则在任何中间件运行之前就被解析完成并以event.context.routeRules的形式对每个中间件可见。这意味着即使是自定义中间件也能读取到当前请求命中的路由规则并进行二次处理。从源码看这一机制在 src/runtime/internal/app.ts 的createRouteRulesMiddleware()L107-L122中实现它通过getRouteRules()按method pathname匹配规则并把命中规则的中间件链redirect、headers、cors等用composeMiddleware组合起来组合链按匹配结果缓存WeakMap保证每个不同的匹配组合只组合一次避免每请求重复构建的性能损耗。源码注释还特别说明event.context.routeRules在更早的~findRoute阶段就被赋值所以无论中间件在链中的位置如何它都能读到完整的规则信息。四、第三层静态资源当静态资源服务开启时大多数 preset 的默认行为Nitro 会把静态资源处理器注册为第一个全局中间件。它先检查请求是否匹配public/目录中的文件再执行其他全局中间件和路由处理器。若命中立即返回静态文件并携带合适的Content-Type、ETag、Last-Modified和Cache-Control响应头请求被终止后续中间件和路由不再执行。静态资源还支持预压缩文件的内容协商gzip、brotli、zstdNitro 会根据Accept-Encoding请求头自动选择压缩版本返回。这意味着你可以在构建期预生成.gz/.br/.zst文件从而在边缘或服务器上省去动态压缩开销。五、第四层全局中间件定义在middleware/目录中的全局中间件在静态资源之后运行。中间件在middleware/目录中按文件名排序字符串排序执行你可以用数字前缀控制顺序如1.logger.ts、2.auth.tsimport { defineHandler } from nitro; export default defineHandler((event) { event.context.info { name: Nitro }; });⚠️警告从中间件中return会关闭请求——返回值会成为响应后续处理器不再执行。除非确实需要提前终结请求否则应避免在中间件中返回内容需要返回响应时应使用路由处理器。详见 Routing Middleware。六、第五层路由级中间件Route-scoped middleware通过handlers配置为特定路由模式注册的中间件在全局中间件之后运行。它只对匹配指定模式的请求生效export default defineConfig({ handlers: [ { route: /api/**, handler: ./server/utils/api-auth.ts, middleware: true, }, ], });与全局中间件自动从middleware/目录注册匹配/**不同路由级中间件需要保持文件位于middleware/目录之外如上面示例中的server/utils/避免目录扫描把它重复注册为全局中间件。附着在匹配路由自身的中间件在最后运行紧接着就是路由处理器。从源码看这一机制由 src/runtime/internal/app.ts 的createRoutedMiddleware()L131-L152实现它以method pathname查找匹配的中间件列表并将组合链缓存在一棵以匹配处理器身份为键的 Trie 中。缓存上限由不同匹配组合的数量决定而非请求路径数量因此高并发下不会因路径爆炸而撑爆内存。七、第六层路由处理器RoutesNitro 将传入请求与routes/目录中定义的文件系统路由进行匹配。文件路径即路由路径导出的事件处理器即路由逻辑export default (event) ({ world: true })关于文件系统路由的更多细节静态路由、动态参数[id]、catch-all[...slug]、方法后缀hello.get.ts等请阅读 Routing Filesystem routing。八、第七层服务器入口Server entry如果定义了服务器入口它会捕获所有未被任何路由匹配的请求充当/**路由处理器import { defineHandler } from nitro; export default defineHandler((event) { if (event.url.pathname /) { return Home page; } });服务器入口适合作为最后一个兜底的通用处理器例如为 SPA 提供入口 HTML、处理健康检查路径等。详见 Server entry。九、第八层渲染器Renderer如果没有路由匹配Nitro 会寻找渲染器处理器可显式定义或自动检测来处理请求import { defineRenderer } from nitro; export default defineRenderer((event) { return !DOCTYPE htmlhtmlbodyHello world/body/html; });渲染器通常用于服务端渲染框架React、Vue、Solid 等的集成场景是请求管道的最后兜底层。详见 Renderer。十、第九层response钩子当响应从上述任意一层创建完成后response钩子运行。它接收最终的Response对象和事件可用于检查或修改响应头import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(response, (res, event) { console.log(Response ${res.status} for ${event.req.url}); }); });注意response钩子对每个响应都会执行——包括静态资源、被中间件终止的请求以及错误响应。因此它非常适合统一埋点、统一添加安全响应头等全局性操作。十一、错误处理Error handling当请求生命周期中任意位置发生错误时Nitro 执行两步流程调用error钩子传入错误和上下文包含 event 与来源标签 tags将错误交给error handler错误处理器转换为 HTTP 响应。11.1 抛出错误从任何处理器或中间件中抛出HTTPError即可用指定的状态码、消息和可选数据结束请求import { defineHandler, HTTPError } from nitro; export default defineHandler((event) { // 消息 详情 throw new HTTPError(Invalid user input, { status: 400 }); // 状态码快捷方式 throw HTTPError.status(400, Bad Request); // 完整对象形式 throw new HTTPError({ status: 400, message: Invalid user input, data: { field: email }, }); });关键区别任何其他抛出的值如普通的new Error()都被视为未处理unhandled错误——响应始终为500且出于安全考虑消息、数据和堆栈不会暴露给客户端。从源码看这一判定逻辑位于 src/runtime/internal/error/prod.ts 的defaultHandler()L16-L48const unhandled error.unhandled ?? !HTTPError.isError(error);当判定为未处理错误时响应体只包含{ status, unhandled: true }不带任何错误消息只有HTTPError或带unhandled: false标记的错误才会序列化statusText、message等字段。此外该处理器对404还有一个特殊行为当配置了非根baseURL且请求路径未带此前缀时会返回302重定向到带baseURL的地址。11.2 默认错误响应格式生产环境下默认错误处理器始终以 JSON 响应{ error: true, status: 400, message: Invalid user input, data: { field: email } }开发环境下程序化请求如fetch、curl 等Accept不含text/html的请求收到相同的 JSON 格式而当请求的Accept头包含text/html即浏览器时Nitro 会渲染一个带 source-map 堆栈跟踪的交互式 HTML 错误页。从源码看开发环境错误页由 src/runtime/internal/error/dev.ts 实现defaultHandler()会先调用loadStackTrace()解析 source map借助youch-core的ErrorParser与source-map包的SourceMapConsumerL102-L128把压缩后的堆栈还原到原始源码位置随后用Youch渲染 HTMLL90-L96并在终端以 ANSI 彩色格式打印未处理错误的完整堆栈L56-L59。JSON 与 HTML 的选择由event.req.headers.get(accept)?.includes(text/html)决定L62。11.3 自定义错误处理器要控制错误响应的格式在 Nitro 配置中把errorHandler设置为一个导出defineErrorHandler处理器的文件路径import { defineConfig } from nitro; export default defineConfig({ errorHandler: ~/error, });import { defineErrorHandler } from nitro; export default defineErrorHandler((error, event) { return new Response([custom error] ${error.message}, { status: error.status || 500, headers: { Content-Type: text/plain }, }); });行为规则返回Response直接发送给客户端返回空undefined交给下一个处理器继续处理处理器数组errorHandler也接受处理器数组按顺序执行第一个返回响应的处理器胜出内置默认处理器始终被追加为最后一项因此总存在兜底响应import { defineConfig } from nitro; export default defineConfig({ errorHandler: [~/error/known-errors, ~/error/fallback], });处理器自身抛错失败会被记录日志链继续走向下一个处理器复用默认渲染每个处理器在第三个参数中收到内置的defaultHandler即{ defaultHandler }你可以在自己的逻辑里直接调用它做默认渲染。从类型定义看NitroErrorHandler的签名是(error, event, { defaultHandler }) MaybePromiseResponse | void见 src/types/handler.ts L115-L130其中defaultHandler可接收{ silent?, json? }选项来控制是否静默、是否强制 JSON。仓库中有一个完整的可运行示例examples/custom-error-handler其中的 error.ts 展示了自定义错误响应、日志记录与defaultHandler复用的组合写法。11.4 仅开发环境的错误渲染devErrorHandler如果只想定制开发服务器的错误渲染不进入生产包可以传入处理器函数作为devErrorHandlerimport { defineConfig } from nitro; import errorHandler from ./error.ts; export default defineConfig({ devErrorHandler: errorHandler, });该配置项同样在 src/types/config.tsL664-L668中定义为NitroErrorHandler类型使用场景是让开发调试输出符合团队风格例如纯 JSON 输出便于自动化测试读取。11.5 观察错误不改变响应仅观察错误而不改变响应请通过插件使用error运行时钩子import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(error, (error, context) { console.error(Captured error:, error); // context.event - H3 event如果可用 // context.tags - 错误来源标签如 request、response、plugin }); });相关的补充能力程序化喂错可以用nitroApp.captureError把错误以编程方式注入同一条错误管道详见 Plugins Programmatic error capture。从源码看captureError的实现会把错误同时推入event.req.context.nitro.errors数组见 src/runtime/virtual/app.ts L13-L20后续钩子可以检查该数组。逐请求错误记录错误会记录在event.req.context.nitro.errors中供后续钩子检查。进程级错误捕获未处理的 Promise rejectionunhandledRejection和未捕获异常uncaughtException会被自动捕获并送入error钩子分别携带标签unhandledRejection与uncaughtException。这一机制在 src/runtime/internal/error/hooks.ts 的trapUnhandledErrors()L8-L11中实现监听两个process事件调用console.error并委托给captureError携带对应标签。十二、服务器关闭Server shutdown当 Nitro 服务器关闭时close钩子被调用。请用它清理数据库连接、定时器或外部服务句柄等资源import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(close, async () { // 清理资源 }); });行为细节close钩子在HTTP 服务器停止接受新连接之后被 await 执行长驻服务器 presetNode.js、Bun、Deno会在收到SIGINT与SIGTERM信号时调用它Serverless / Edge preset 没有关闭信号只有平台关闭运行时或部署环境触发时钩子才会运行。从源码看close钩子的触发封装在 src/runtime/internal/shutdown.ts 的setupCloseHooks()L14-L19中它包装了server.close()无论关闭来自信号路径还是显式调用都会在关闭完成后执行close钩子钩子只执行一次强制关闭与优雅关闭共享同一个 Promise即使底层关闭失败也会执行。仓库的 test/unit/close-hooks.test.ts 对钩子的触发时机与幂等性有专门覆盖。十三、运行时钩子参考表所有运行时钩子都通过运行时插件使用nitroApp.hooks.hook()注册钩子签名触发时机request(event: HTTPEvent) void \| Promisevoid每个请求开始、路由解析之前。response(res: Response, event: HTTPEvent) void \| Promisevoid响应创建之后、发送之前。error(error: Error, context: { event?, tags? }) void生命周期中捕获到任何错误时。close() voidNitro 服务器关闭时。扩展性NitroRuntimeHooks接口是可扩展augmentable的——部署 preset如 Cloudflare可以为其追加平台特定的钩子。类型定义位于 src/types/runtime/nitro.tsL69-L73其中error钩子的类型即CaptureErrorL60-L61签名与上表一致。更多插件用法与钩子示例请阅读 Plugins。十四、小结如何把生命周期用于实战综合上述九层请求管道与错误处理机制可以提炼出几条实战准则请求入口侧把跨请求的全局逻辑访问日志、请求 ID 生成放在request钩子中它最先执行且错误不会中断管道。响应出口侧把统一响应头、埋点统计放在response钩子中它对包括静态资源与错误响应在内的所有响应生效。中间件分工静态资源处理最先执行其次是全局中间件最后是路由级中间件需要提前终结请求时使用return但应谨慎——它会让后续管道全部失效。兜底链路路由 → 服务器入口 → 渲染器逐级兜底确保任何请求最终都有响应可回。错误策略业务可控错误一律抛出HTTPError携带状态码与 data不可控错误保持未处理状态由默认处理器返回500JSON需要定制格式时用errorHandler数组 defaultHandler兜底仅改开发体验时用devErrorHandler。进程收尾在close钩子中关闭数据库连接与定时器并理解长驻与 Serverless preset 在关闭信号上的差异。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nitro 请求生命周期与错误处理完全指南：从 Request Hook 到服务器关闭
Nitro 请求生命周期与错误处理完全指南从 Request Hook 到服务器关闭【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro本篇技术指南以 Nitro 官方文档 docs/1.docs/50.lifecycle.md 为骨架深入讲解一个请求从进入 Nitro 到响应返回所经过的每一层处理环节以及错误处理与服务器关闭的完整机制。读者读完将掌握 Nitro 请求管道中各层级的执行顺序、如何在插件中挂载request/response/error/close运行时钩子、如何用HTTPError精确控制错误响应以及如何通过errorHandler/devErrorHandler定制生产与开发环境的错误输出。一、Nitro 的请求生命周期总览Nitro 是一个下一代服务器工具包其核心设计之一是请求可以被请求管道中任意一层拦截并终止无论是否携带响应。理解这些层级的执行顺序是编写可靠中间件、路由与错误处理代码的前提。一个传入请求按以下顺序依次经过各层任意一层都可以终止请求request钩子通过运行时插件注册Route rules路由规则来自routeRules配置静态资源处理public/目录作为第一个全局中间件全局中间件middleware/目录自动注册路由级中间件通过handlers配置的路由范围中间件路由处理器routes/目录服务器入口Server entry未匹配任何路由时兜底渲染器Renderer作为最后的兜底response钩子响应创建后、发送前执行下面逐层展开。二、第一层request钩子request是每个传入请求执行的第一段代码通过运行时插件注册import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(request, (event) { console.log(Incoming request on ${event.req.url}); }); });注意在request钩子内抛出的错误会被error钩子捕获而不会终止请求管道。这意味着你可以放心地在其中做日志、鉴权预检查等操作而不必担心意外中断请求。从源码看插件的初始化发生在 Nitro 应用首次创建时。在 src/runtime/internal/app.ts 中useNitroApp()会创建应用实例并调用initNitroPlugins(instance)L25-L28运行时插件正是通过这一步完成挂载随后nitroApp.hooks.hook(...)注册的钩子才会对每个请求生效。三、第二层Route rules 路由规则与请求匹配的 route rules来自 Nitro 配置在全局中间件之前执行。Route rules 以中间件形式运行其中大部分规则只修改响应而不会终止请求例如添加响应头、设置缓存策略等import { defineConfig } from nitro; export default defineConfig({ routeRules: { /**: { headers: { x-nitro: first } } } })关键细节匹配到的规则在任何中间件运行之前就被解析完成并以event.context.routeRules的形式对每个中间件可见。这意味着即使是自定义中间件也能读取到当前请求命中的路由规则并进行二次处理。从源码看这一机制在 src/runtime/internal/app.ts 的createRouteRulesMiddleware()L107-L122中实现它通过getRouteRules()按method pathname匹配规则并把命中规则的中间件链redirect、headers、cors等用composeMiddleware组合起来组合链按匹配结果缓存WeakMap保证每个不同的匹配组合只组合一次避免每请求重复构建的性能损耗。源码注释还特别说明event.context.routeRules在更早的~findRoute阶段就被赋值所以无论中间件在链中的位置如何它都能读到完整的规则信息。四、第三层静态资源当静态资源服务开启时大多数 preset 的默认行为Nitro 会把静态资源处理器注册为第一个全局中间件。它先检查请求是否匹配public/目录中的文件再执行其他全局中间件和路由处理器。若命中立即返回静态文件并携带合适的Content-Type、ETag、Last-Modified和Cache-Control响应头请求被终止后续中间件和路由不再执行。静态资源还支持预压缩文件的内容协商gzip、brotli、zstdNitro 会根据Accept-Encoding请求头自动选择压缩版本返回。这意味着你可以在构建期预生成.gz/.br/.zst文件从而在边缘或服务器上省去动态压缩开销。五、第四层全局中间件定义在middleware/目录中的全局中间件在静态资源之后运行。中间件在middleware/目录中按文件名排序字符串排序执行你可以用数字前缀控制顺序如1.logger.ts、2.auth.tsimport { defineHandler } from nitro; export default defineHandler((event) { event.context.info { name: Nitro }; });⚠️警告从中间件中return会关闭请求——返回值会成为响应后续处理器不再执行。除非确实需要提前终结请求否则应避免在中间件中返回内容需要返回响应时应使用路由处理器。详见 Routing Middleware。六、第五层路由级中间件Route-scoped middleware通过handlers配置为特定路由模式注册的中间件在全局中间件之后运行。它只对匹配指定模式的请求生效export default defineConfig({ handlers: [ { route: /api/**, handler: ./server/utils/api-auth.ts, middleware: true, }, ], });与全局中间件自动从middleware/目录注册匹配/**不同路由级中间件需要保持文件位于middleware/目录之外如上面示例中的server/utils/避免目录扫描把它重复注册为全局中间件。附着在匹配路由自身的中间件在最后运行紧接着就是路由处理器。从源码看这一机制由 src/runtime/internal/app.ts 的createRoutedMiddleware()L131-L152实现它以method pathname查找匹配的中间件列表并将组合链缓存在一棵以匹配处理器身份为键的 Trie 中。缓存上限由不同匹配组合的数量决定而非请求路径数量因此高并发下不会因路径爆炸而撑爆内存。七、第六层路由处理器RoutesNitro 将传入请求与routes/目录中定义的文件系统路由进行匹配。文件路径即路由路径导出的事件处理器即路由逻辑export default (event) ({ world: true })关于文件系统路由的更多细节静态路由、动态参数[id]、catch-all[...slug]、方法后缀hello.get.ts等请阅读 Routing Filesystem routing。八、第七层服务器入口Server entry如果定义了服务器入口它会捕获所有未被任何路由匹配的请求充当/**路由处理器import { defineHandler } from nitro; export default defineHandler((event) { if (event.url.pathname /) { return Home page; } });服务器入口适合作为最后一个兜底的通用处理器例如为 SPA 提供入口 HTML、处理健康检查路径等。详见 Server entry。九、第八层渲染器Renderer如果没有路由匹配Nitro 会寻找渲染器处理器可显式定义或自动检测来处理请求import { defineRenderer } from nitro; export default defineRenderer((event) { return !DOCTYPE htmlhtmlbodyHello world/body/html; });渲染器通常用于服务端渲染框架React、Vue、Solid 等的集成场景是请求管道的最后兜底层。详见 Renderer。十、第九层response钩子当响应从上述任意一层创建完成后response钩子运行。它接收最终的Response对象和事件可用于检查或修改响应头import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(response, (res, event) { console.log(Response ${res.status} for ${event.req.url}); }); });注意response钩子对每个响应都会执行——包括静态资源、被中间件终止的请求以及错误响应。因此它非常适合统一埋点、统一添加安全响应头等全局性操作。十一、错误处理Error handling当请求生命周期中任意位置发生错误时Nitro 执行两步流程调用error钩子传入错误和上下文包含 event 与来源标签 tags将错误交给error handler错误处理器转换为 HTTP 响应。11.1 抛出错误从任何处理器或中间件中抛出HTTPError即可用指定的状态码、消息和可选数据结束请求import { defineHandler, HTTPError } from nitro; export default defineHandler((event) { // 消息 详情 throw new HTTPError(Invalid user input, { status: 400 }); // 状态码快捷方式 throw HTTPError.status(400, Bad Request); // 完整对象形式 throw new HTTPError({ status: 400, message: Invalid user input, data: { field: email }, }); });关键区别任何其他抛出的值如普通的new Error()都被视为未处理unhandled错误——响应始终为500且出于安全考虑消息、数据和堆栈不会暴露给客户端。从源码看这一判定逻辑位于 src/runtime/internal/error/prod.ts 的defaultHandler()L16-L48const unhandled error.unhandled ?? !HTTPError.isError(error);当判定为未处理错误时响应体只包含{ status, unhandled: true }不带任何错误消息只有HTTPError或带unhandled: false标记的错误才会序列化statusText、message等字段。此外该处理器对404还有一个特殊行为当配置了非根baseURL且请求路径未带此前缀时会返回302重定向到带baseURL的地址。11.2 默认错误响应格式生产环境下默认错误处理器始终以 JSON 响应{ error: true, status: 400, message: Invalid user input, data: { field: email } }开发环境下程序化请求如fetch、curl 等Accept不含text/html的请求收到相同的 JSON 格式而当请求的Accept头包含text/html即浏览器时Nitro 会渲染一个带 source-map 堆栈跟踪的交互式 HTML 错误页。从源码看开发环境错误页由 src/runtime/internal/error/dev.ts 实现defaultHandler()会先调用loadStackTrace()解析 source map借助youch-core的ErrorParser与source-map包的SourceMapConsumerL102-L128把压缩后的堆栈还原到原始源码位置随后用Youch渲染 HTMLL90-L96并在终端以 ANSI 彩色格式打印未处理错误的完整堆栈L56-L59。JSON 与 HTML 的选择由event.req.headers.get(accept)?.includes(text/html)决定L62。11.3 自定义错误处理器要控制错误响应的格式在 Nitro 配置中把errorHandler设置为一个导出defineErrorHandler处理器的文件路径import { defineConfig } from nitro; export default defineConfig({ errorHandler: ~/error, });import { defineErrorHandler } from nitro; export default defineErrorHandler((error, event) { return new Response([custom error] ${error.message}, { status: error.status || 500, headers: { Content-Type: text/plain }, }); });行为规则返回Response直接发送给客户端返回空undefined交给下一个处理器继续处理处理器数组errorHandler也接受处理器数组按顺序执行第一个返回响应的处理器胜出内置默认处理器始终被追加为最后一项因此总存在兜底响应import { defineConfig } from nitro; export default defineConfig({ errorHandler: [~/error/known-errors, ~/error/fallback], });处理器自身抛错失败会被记录日志链继续走向下一个处理器复用默认渲染每个处理器在第三个参数中收到内置的defaultHandler即{ defaultHandler }你可以在自己的逻辑里直接调用它做默认渲染。从类型定义看NitroErrorHandler的签名是(error, event, { defaultHandler }) MaybePromiseResponse | void见 src/types/handler.ts L115-L130其中defaultHandler可接收{ silent?, json? }选项来控制是否静默、是否强制 JSON。仓库中有一个完整的可运行示例examples/custom-error-handler其中的 error.ts 展示了自定义错误响应、日志记录与defaultHandler复用的组合写法。11.4 仅开发环境的错误渲染devErrorHandler如果只想定制开发服务器的错误渲染不进入生产包可以传入处理器函数作为devErrorHandlerimport { defineConfig } from nitro; import errorHandler from ./error.ts; export default defineConfig({ devErrorHandler: errorHandler, });该配置项同样在 src/types/config.tsL664-L668中定义为NitroErrorHandler类型使用场景是让开发调试输出符合团队风格例如纯 JSON 输出便于自动化测试读取。11.5 观察错误不改变响应仅观察错误而不改变响应请通过插件使用error运行时钩子import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(error, (error, context) { console.error(Captured error:, error); // context.event - H3 event如果可用 // context.tags - 错误来源标签如 request、response、plugin }); });相关的补充能力程序化喂错可以用nitroApp.captureError把错误以编程方式注入同一条错误管道详见 Plugins Programmatic error capture。从源码看captureError的实现会把错误同时推入event.req.context.nitro.errors数组见 src/runtime/virtual/app.ts L13-L20后续钩子可以检查该数组。逐请求错误记录错误会记录在event.req.context.nitro.errors中供后续钩子检查。进程级错误捕获未处理的 Promise rejectionunhandledRejection和未捕获异常uncaughtException会被自动捕获并送入error钩子分别携带标签unhandledRejection与uncaughtException。这一机制在 src/runtime/internal/error/hooks.ts 的trapUnhandledErrors()L8-L11中实现监听两个process事件调用console.error并委托给captureError携带对应标签。十二、服务器关闭Server shutdown当 Nitro 服务器关闭时close钩子被调用。请用它清理数据库连接、定时器或外部服务句柄等资源import { definePlugin } from nitro; export default definePlugin((nitroApp) { nitroApp.hooks.hook(close, async () { // 清理资源 }); });行为细节close钩子在HTTP 服务器停止接受新连接之后被 await 执行长驻服务器 presetNode.js、Bun、Deno会在收到SIGINT与SIGTERM信号时调用它Serverless / Edge preset 没有关闭信号只有平台关闭运行时或部署环境触发时钩子才会运行。从源码看close钩子的触发封装在 src/runtime/internal/shutdown.ts 的setupCloseHooks()L14-L19中它包装了server.close()无论关闭来自信号路径还是显式调用都会在关闭完成后执行close钩子钩子只执行一次强制关闭与优雅关闭共享同一个 Promise即使底层关闭失败也会执行。仓库的 test/unit/close-hooks.test.ts 对钩子的触发时机与幂等性有专门覆盖。十三、运行时钩子参考表所有运行时钩子都通过运行时插件使用nitroApp.hooks.hook()注册钩子签名触发时机request(event: HTTPEvent) void \| Promisevoid每个请求开始、路由解析之前。response(res: Response, event: HTTPEvent) void \| Promisevoid响应创建之后、发送之前。error(error: Error, context: { event?, tags? }) void生命周期中捕获到任何错误时。close() voidNitro 服务器关闭时。扩展性NitroRuntimeHooks接口是可扩展augmentable的——部署 preset如 Cloudflare可以为其追加平台特定的钩子。类型定义位于 src/types/runtime/nitro.tsL69-L73其中error钩子的类型即CaptureErrorL60-L61签名与上表一致。更多插件用法与钩子示例请阅读 Plugins。十四、小结如何把生命周期用于实战综合上述九层请求管道与错误处理机制可以提炼出几条实战准则请求入口侧把跨请求的全局逻辑访问日志、请求 ID 生成放在request钩子中它最先执行且错误不会中断管道。响应出口侧把统一响应头、埋点统计放在response钩子中它对包括静态资源与错误响应在内的所有响应生效。中间件分工静态资源处理最先执行其次是全局中间件最后是路由级中间件需要提前终结请求时使用return但应谨慎——它会让后续管道全部失效。兜底链路路由 → 服务器入口 → 渲染器逐级兜底确保任何请求最终都有响应可回。错误策略业务可控错误一律抛出HTTPError携带状态码与 data不可控错误保持未处理状态由默认处理器返回500JSON需要定制格式时用errorHandler数组 defaultHandler兜底仅改开发体验时用devErrorHandler。进程收尾在close钩子中关闭数据库连接与定时器并理解长驻与 Serverless preset 在关闭信号上的差异。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考