遵循最佳实践

遵循这些指南，构建高性能且可维护的 Nuxt 模块。

能力越大，责任越大。虽然模块功能强大，但在编写模块时，请记住以下最佳实践，以保持应用的高性能和极佳的开发体验。

处理异步 Setup

如我们所见，Nuxt 模块可以是异步的。例如，你可能想开发一个需要获取某些 API 或调用异步函数的模块。

然而，请注意异步行为，因为 Nuxt 会等待你的模块完成 setup，然后才会处理下一个模块并启动开发服务器、构建过程等。建议将耗时逻辑推迟到 Nuxt 钩子（hooks）中处理。

如果你的模块设置（setup）耗时超过 1 秒，Nuxt 将发出警告。

为你的导出添加前缀

Nuxt 模块应为其暴露的任何配置、插件、API、组合式函数（composable）、组件或服务器路由提供明确的前缀，以避免与其他模块、Nuxt 内部结构或用户定义的代码发生冲突。

理想情况下，使用你的模块名称作为前缀。例如，如果你的模块名为 nuxt-foo

类型	❌ 避免	✅ 建议
组件	`<Button>`, `<Modal>`	`<FooButton>`, `<FooModal>`
可组合项	`useData()`, `useModal()`	`useFooData()`, `useFooModal()`
服务器路由	`/api/track`, `/api/data`	`/api/_foo/track`, `/api/_foo/data`

服务器路由

这对于服务器路由尤为重要，因为像 /api/auth、/api/login 或 /api/user 这样常见的路径非常有可能已经被应用程序使用了。

使用基于你的模块名称的唯一前缀

/api/_foo/...（使用下划线前缀）
/_foo/...（用于非 API 路由）

使用生命周期钩子

当你的模块需要执行一次性设置任务（如生成配置文件、设置数据库或安装依赖）时，请使用生命周期钩子，而不是在你的主 setup 函数中运行这些逻辑。

import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
import { isLess } from 'verkit'

export default defineNuxtModule({
  meta: {
    name: 'my-database-module',
    version: '1.0.0',
  },
  async onInstall (nuxt) {
    // One-time setup: create database schema, generate config files, etc.
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (nuxt, options, previousVersion) {
    // Handle version-specific migrations
    if (isLess(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // Regular setup logic that runs on every build
    addServerHandler({ /* ... */ })
  },
})