Lzh on GitHub

服务器端工具

享受自动导入的服务器工具，并用您自己的工具进行扩展。

自动导入

当阅读文档其余部分时，你可能会注意到示例中没有使用工具函数的 导入语句。这是因为在使用完整的 tree-shaking 支持时，Nitro 通过 unjs/unimport 自动导入工具函数，因此你无需手动导入！

H3 工具

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

Read more in H3 文档.

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) (experimental)
  • useRuntimeConfig(event?)
  • useStorage(base?)
  • useNitroApp()
  • defineNitroPlugin(plugin)
  • nitroPlugin(plugin)
  • getRouteRules(event)
Read more in 查看 源代码 以获取可用 Nitro 自动导入的列表.
Read more in 当运行 `prepare` 或 `dev` 命令时，会自动为全局自动导入生成类型。请参阅 TypeScript 指南，获取 IDE 支持.

手动导入

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

您可以从虚拟的 #imports 文件中显式导入它们。手动从 #imports 导入仍然具有 tree-shaking 优化的好处。

server/plugins/test.ts
import { useStorage } from '#imports'
#imports 是 Nuxt 3 自动导入功能的底层实现入口，它集中了以下内容的类型声明和实际导出：
  • Vue 的组合式 API（如 ref, computed）
  • Nuxt 提供的工具函数（如 useAsyncData）
  • 其他模块通过 autoImports 注册的 API
第三方库组件的导入方式：若需从 node_modules 导入组件（如 @heroicons/vue），需使用以下方法：
<script setup lang="ts">
import { BeakerIcon } from '@heroicons/vue/24/solid' // 直接指定 node_modules 路径
</script>

异步上下文 (实验性)

Nitro (2.6+) 启用了一种新的服务器开发体验，以便将应用程序逻辑拆分为更小的 “可组合(composable)” 工具，这些工具彼此完全解耦，并且可以直接访问共享上下文（请求事件），而无需将其传递。此模式受 Vue Composition 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())
}