遵循最佳实践

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

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

处理异步初始化

如前所述，Nuxt 模块可以是异步的。例如，你可能需要开发一个模块，需要调用某个 API 或异步函数。

但是，请谨慎使用异步行为，因为 Nuxt 会等待你的模块完成初始化后，才会继续加载下一个模块并启动开发服务器、构建流程等。建议将耗时较长的逻辑延迟到 Nuxt 钩子中执行。

如果你的模块初始化时间超过 1 秒，Nuxt 会发出警告。

给导出加前缀

Nuxt 模块应为任何暴露的配置、插件、API、组合式函数、组件或服务器路由提供明确的前缀，以避免与其他模块、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 semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-database-module',
    version: '1.0.0',
  },
  async onInstall (nuxt) {
    // 一次性初始化：创建数据库 schema，生成配置文件等
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (nuxt, options, previousVersion) {
    // 处理版本迁移
    if (semver.lt(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // 常规初始化逻辑，每次构建时执行
    addServerHandler({ /* ... */ })
  },
})