实用工具 Server Utils

享受自动导入的服务器实用程序并使用您自己的实用程序进行扩展。

自动导入 Auto imports

阅读其余文档时，您可能会注意到使用实用程序的示例中没有“导入”。 这是因为 Nitro 使用 unjs/unimport 在与完整的 tree-shaking 支持一起使用时自动导入实用程序，所以您不必这样做！

H3 实用程序 H3 utils

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

相关阅读：H3 Docs

实用程序目录 utils directory

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

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

utils/sum.ts
ts
export function useSum(a: number, b: number) {
  return a + b
}

在你的 routes/index.ts 文件中使用它而不导入它：

routes/index.ts
ts
export default defineEventHandler(() => {
  const sum = useSum(1, 2) // auto-imported
  return { sum }
})

自带实用程序 Nitro utils

Nitro 还公开了几个内置实用程序：

  • defineCachedFunction(fn, options) / cachedFunction(fn, options)
  • defineCachedEventHandler(handler, options) / cachedEventHandler(handler, options)
  • defineRenderHandler(handler)
  • defineRouteMeta(options) (experimental)
  • useRuntimeConfig(event?)
  • useAppConfig(event?)
  • useStorage(base?)
  • useNitroApp()
  • defineNitroPlugin(plugin)
  • nitroPlugin(plugin)
  • getRouteRules(event)
相关阅读：检查源代码以获取可用的 Nitro 自动导入列表。

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

手动导入 Manual imports

对于某些极端情况（IDE 支持和 node_modules 中的库），不可能依赖自动导入。

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

!TIP 从 #imports 手动导入仍然具有 tree-shaking 的好处。

plugins/test.ts
js
import { useStorage } from '#imports'

异步上下文 Async Context (实验)

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

该功能目前支持 Node.js 和 Bun 运行时，并且即将支持其他支持 AsyncLocalStorage 接口的预设。

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

ts
nitro.config.ts
ts
export default defineNitroConfig({
  experimental: {
    asyncContext: true
  }
})

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

ts
使用异步上下文
ts
// routes/index.ts
export default defineEventHandler(async () => {
  const user = await useAuth()
})

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