Nuxt3自定义模块如何正确导出组合式函数并在项目中导入？

1. 完善package.json的exports配置 #

你的package.json仅配置了根路径，这是导致深层路径导入报错、无法直接从包名导入的核心原因。修改exports字段，补充runtime目录的导出规则：

{
  "exports": {
    ".": {
      "types": "./dist/types.d.ts",
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs"
    },
    "./dist/runtime/composables/*": "./dist/runtime/composables/*.mjs",
    "./useSomething": "./dist/runtime/composables/useSomething.mjs"
  },
  "types": "./dist/types.d.ts",
  "files": [
    "dist"
  ]
}

• ./dist/runtime/composables/*通配符导出，解决深层路径导入时的"Missing export"报错
• ./useSomething单独导出，支持用户通过import useSomething from 'nuxt-something/useSomething'手动导入

2. 确保module.ts的自动导入配置正确 #

你已经用addImports注册了组合式函数，需确认路径解析逻辑正确，确保自动导入生效：

// module.ts
import { defineNuxtModule, addImports } from '@nuxt/kit'
import { fileURLToPath } from 'node:url'
import { join } from 'node:path'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-something',
    configKey: 'something'
  },
  setup(options, nuxt) {
    // 注册自动导入的组合式函数
    addImports({
      name: 'useSomething',
      from: join(fileURLToPath(import.meta.url), '../runtime/composables/useSomething')
    })

    // 给runtime目录配置别名，避免路径解析问题
    nuxt.options.alias['#something'] = join(fileURLToPath(import.meta.url), '../runtime')
  }
})

配置完成后，用户无需手动导入，可直接在组件/页面中调用useSomething。

3. 检查编译与发布环节 #

• 确认编译脚本（如nuxi build或自定义tsup/vite脚本）已将runtime/composables目录下的文件编译为ES模块，输出到dist目录
• 检查package.json的files字段包含dist，确保所有编译产物都被发布到npm

4. 新项目测试 #

发布后在新项目中安装模块并注册：

npm install nuxt-something

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-something']
})

此时用户既可以直接使用useSomething（自动导入生效），也可以通过import { useSomething } from 'nuxt-something'手动导入。

排查要点 #

• 若仍报导出缺失，检查npm包的dist目录是否包含所有预期文件
• 确认编译后的文件扩展名与exports配置中的一致（如.mjs）

内容的提问来源于stack exchange，提问作者Antoine GUGLIELMI