如何在nuxt-module中导入项目根目录下的自定义配置文件

报错根因 #

你遇到的Unexpected token '<'错误是因为nuxt.config.js以及同目录的配置文件是在Node.js原生环境加载的，默认不支持解析Vue单文件组件的<template>语法，直接在配置文件中导入.vue组件会在Node加载阶段就解析失败，根本走不到Nuxt的构建流程。

实现方案 #

完全不需要在配置文件里直接导入组件，改成传递组件路径字符串，在你开发的Nuxt模块侧处理注册逻辑即可，具体步骤如下：

1. 编写file.config.js配置
   只需要传入自定义组件的相对路径即可，不需要直接导入组件实例：

// 和nuxt.config.js同目录的file.config.js
export default {
  // 定义要覆盖的组件映射：组件名 => 组件相对项目根目录的路径
  customComponents: {
    MyButton: './components/MyCustomButton.vue',
    MyCard: './components/MyCustomCard.vue'
  }
}

2. 在Nuxt模块中处理配置，实现组件覆盖
   用Nuxt官方提供的addComponent工具方法注册组件，通过调整优先级实现自定义组件覆盖默认组件：

// 你开发的nuxt-module入口文件
import { defineNuxtModule, addComponent, resolveAlias } from '@nuxt/kit'
import { fileURLToPath } from 'node:url'
import { dirname, join } from 'node:path'

export default defineNuxtModule({
  async setup(options, nuxt) {
    // 读取用户项目根目录下的file.config.js
    const userConfigPath = join(nuxt.options.rootDir, 'file.config.js')
    const userConfig = await import(userConfigPath).then(mod => mod.default || mod)
    const customCompMap = userConfig.customComponents || {}

    // 注册用户自定义组件，设置高优先级
    for (const [compName, compPath] of Object.entries(customCompMap)) {
      const resolvedPath = resolveAlias(compPath)
      addComponent({
        name: compName,
        filePath: resolvedPath,
        priority: 10 // 优先级高于默认组件即可自动覆盖
      })
    }

    // 注册模块自带的默认组件，设置低优先级
    const moduleRuntimeDir = dirname(fileURLToPath(import.meta.url))
    addComponent({
      name: 'MyButton',
      filePath: join(moduleRuntimeDir, './runtime/components/DefaultButton.vue'),
      priority: 1
    })
    addComponent({
      name: 'MyCard',
      filePath: join(moduleRuntimeDir, './runtime/components/DefaultCard.vue'),
      priority: 1
    })
  }
})

替代方案（别名覆盖） #

如果你的模块代码里是手动导入组件而不是用自动注册，可以通过别名覆盖的方式实现：

// 在模块的setup方法中添加别名逻辑
const defaultButtonPath = join(moduleRuntimeDir, './runtime/components/DefaultButton.vue')
nuxt.options.alias['#your-module/components/Button'] = customCompMap.MyButton || defaultButtonPath

之后在模块的所有业务代码里都用别名导入组件即可，用户传了自定义组件就会自动走自定义路径：

import Button from '#your-module/components/Button'

注意事项 #

• 所有Node侧运行的配置文件里不要直接导入前端资源（包括.vue组件、样式、静态资源等），统一用路径字符串传递，交给Nuxt构建链路处理解析
• 自定义组件如果包含TS、JSX等特殊语法也不需要额外处理，Nuxt的构建流程会自动完成转译

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