服务器工具

自动导入

在阅读其余文档时，您可能会注意到在使用工具的示例中没有 imports。这是因为 Nitro 使用了 unjs/unimport 在支持完整树摇身的情况下自动导入工具，所以您无需手动导入！

H3 工具

Nitro 启用所有 h3 工具作为自动导入，因此您可以使用 defineEventHandler、readBody 等，而无需手动导入它们。

`utils` 目录

您可以在 server/utils/ 目录中添加特定于应用程序的工具，它们将在使用时被自动导入。utils 目录及其子目录中的每个导出将在您的应用程序中全局可用。

示例： 创建一个 server/utils/sum.ts 文件，导出一个函数 useSum：

server/utils/sum.ts

export function useSum(a: number, b: number) { return a + b }

在您的 server/routes/index.ts 文件中使用它而无需导入：

server/routes/index.ts

export default defineEventHandler(() => {
  const sum = useSum(1, 2) // 自动导入
  return { sum }
})

Nitro 工具

Nitro 还提供了几个内置工具：

defineCachedFunction(fn, options) / cachedFunction(fn, options)
defineCachedEventHandler(handler, options) / cachedEventHandler(handler, options)
defineRenderHandler(handler)
defineRouteMeta(options) (实验性)
useRuntimeConfig(event?)
useStorage(base?)
useNitroApp()
defineNitroPlugin(plugin)
nitroPlugin(plugin)
getRouteRules(event)

查看源码以获取可用 Nitro 自动导入的列表。

在运行 prepare 或 dev 命令时，全局自动导入的类型会自动生成。有关 IDE 支持，请参见 TypeScript 指南。

手动导入

对于某些边缘情况（IDE 支持和 node_modules 中的库），无法依赖自动导入。

您可以从虚拟的 #imports 文件中显式导入它们。

从 #imports 手动导入仍然具有树摇身的好处。

server/plugins/test.ts

import { useStorage } from '#imports'

异步上下文（实验性）

Nitro (2.6+) 启用了一种新的服务器开发体验，以便将应用程序逻辑拆分成更小的“可组合”工具，这些工具彼此完全解耦，可以直接访问共享上下文（请求事件），而无需将其传递。这种模式的灵感来自于 Vue 组合 API，并由 unjs/unctx 提供支持。

此功能目前支持 Node.js 和 Bun 运行时，并很快会在支持 AsyncLocalStorage 接口的其他预设上推出。

为了启用异步上下文特性，您必须启用 asyncContext 标志：

export default defineNitroConfig({
  experimental: {
    asyncContext: true
  }
});

启用此标志后，您可以在任何工具或组合中使用 useEvent()（自动导入）来访问请求事件，而无需手动传递它：

// server/routes/index.ts
export default defineEventHandler(async () => {
  const user = await useAuth()
})

// server/utils/auth.ts
export function useAuth() {
  return useSession(useEvent())
}

Edit this page

迁移指南

服务器路由