如何让Nuxt模块提供的Composable实现自动导入？

问题描述 #

我在开发自定义Nuxt模块时，希望模块提供的Composable无需手动导入就能在组件中直接使用。目前必须从#imports导入useTest，否则会抛出“500 - useTest is not defined”错误，现有代码如下：

模块代码（src/module.ts） #

import { fileURLToPath } from "url";
import {
  defineNuxtModule,
  createResolver,
  addImportsDir,
} from "@nuxt/kit";

export interface ModuleOptions {
  addPlugin: boolean;
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: "my-module",
    configKey: "myModule",
  },
  defaults: {
    addPlugin: true,
  },
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url);
    const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));

    addImportsDir(resolve(runtimeDir, "composables"));
  },
});

Composable代码（src/runtime/composables/useTest.ts） #

export function useTest() {
  console.log("run useTest");

  return {
    test: () => {
      console.log("run test method provided by useTest");
    },
  };
}

测试组件（playground/app.vue） #

<template>
  <div>
    Nuxt module playground!
  </div>
</template>

<script setup>
import { useTest } from "#imports"; // 希望移除这行代码
useTest();
</script>

解决方案 #

方法1：确认addImportsDir路径正确性（推荐批量导入） #

你当前已经使用了addImportsDir，但需要确保路径指向正确的composables目录。可以在模块的setup函数中添加日志验证路径：

setup(options, nuxt) {
  const { resolve } = createResolver(import.meta.url);
  const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));
  const composablesDir = resolve(runtimeDir, "composables");
  console.log("Composables目录路径：", composablesDir); // 验证路径是否正确
  addImportsDir(composablesDir);
}

方法2：手动注册单个Composable（更精准） #

如果批量导入不生效，可以使用addImports单独注册每个Composable，确保Nuxt明确识别要自动导入的函数：

// 在src/module.ts中导入addImports
import { defineNuxtModule, createResolver, addImports } from "@nuxt/kit";

// ...

setup(options, nuxt) {
  const { resolve } = createResolver(import.meta.url);
  const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));

  addImports({
    name: "useTest", // 要自动导入的函数名
    from: resolve(runtimeDir, "composables/useTest"), // 函数所在文件路径
  });
}

后续验证步骤 #

1. 重启Nuxt服务：模块配置修改后需要重启服务才能生效
2. 移除手动导入：将playground/app.vue中的import { useTest } from "#imports";删除
3. 测试运行：直接调用useTest()，确认不再报错，控制台能正常输出日志

原理说明 #

Nuxt的自动导入依赖unjs/unimport插件，模块中通过addImportsDir或addImports注册的Composable，会被Nuxt在编译阶段自动注入到组件的<script setup>中，无需手动导入即可使用。

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