Nuxt 3模块本地正常但NPM引入异常问题求助

问题背景 #

我开发了一个包含组件、样式表和图片的Nuxt3模块，已将其添加到目标应用的package.json的modules数组中：

modules: ['@zadigetvoltaire/nuxt-gtm', 'cec-vue-lib'],

本地通过node_modules软链访问时一切正常，但发布到NPM后引入出现两个问题：

1. 图片找不到错误：

Pre-transform error: Failed to resolve import "cec-logo-colour-155x70px.png" from "node_modules/cec-vue-lib/dist/runtime/components/cecHeader.vue". Does the file exist?

2. 组件的<script setup>标签中出现onMounted未定义的错误

模块核心代码 #

module.ts #

import { defineNuxtModule, addPlugin, createResolver, addComponentsDir } from '@nuxt/kit';

// Module options TypeScript interface definition
export interface ModuleOptions {}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'cec-vue-lib',
    configKey: 'cec-vue-lib'
  },
  // Default configuration options of the Nuxt module
  defaults: {},
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url);

    // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack`
    addPlugin(resolver.resolve('./runtime/plugin'))
    addComponentsDir({
      path: resolver.resolve('./runtime/components')
    });

    nuxt.options.css.push(resolver.resolve('./runtime/assets/style.css'))
    nuxt.hook('nitro:config', async (nitroConfig) => {
      nitroConfig.publicAssets ||= []
      nitroConfig.publicAssets.push({
        dir: resolver.resolve('./runtime/public'),
        maxAge: 60 * 60 * 24 * 365 // 1 year
      })
    });
  }})

package.json #

{
  "name": "cec-vue-lib",
  "version": "1.0.5",
  "description": "Nuxt components and assets",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/types.d.ts",
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs"
    }
  },
  "main": "./dist/module.cjs",
  "types": "./dist/types.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "prepack": "nuxt-module-build build",
    "dev": "nuxi dev playground",
    "dev:build": "nuxi build playground",
    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
    "lint": "eslint .",
    "test": "vitest run",
    "test:watch": "vitest watch",
    "link": "npm link"
  },
  "dependencies": {
    "@nuxt/kit": "^3.11.2"
  },
  "devDependencies": {
    "@types/node": "^20.12.4",
    "@nuxt/devtools": "latest",
    "@nuxt/eslint-config": "^0.2.0",
    "@nuxt/module-builder": "^0.5.5",
    "@nuxt/schema": "^3.11.2",
    "@nuxt/test-utils": "^3.12.0",
    "changelogen": "^0.5.5",
    "eslint": "^8.57.0",
    "nuxt": "^3.11.2",
    "vitest": "^1.4.0"
  }
}

问题排查与修复方案 #

1. 图片资源找不到的问题 #

核心原因

• 发布NPM时，图片资源未被正确打包到dist目录；组件中直接用文件名引用图片，Nuxt无法在node_modules路径下解析资源。
• 当前package.json仅打包dist目录，但如果构建过程没把runtime/public下的图片复制到dist/runtime/public，就会导致资源缺失。

修复步骤

• 确保资源被打包：检查nuxt-module-build的构建结果，确认dist/runtime/public目录存在并包含所有图片。如果缺失，可以在构建脚本中添加资源复制命令，或者调整模块配置确保publicAssets路径正确。
• 修改组件图片引用方式：在组件中使用Nuxt的public资源路径规则，或者通过useRuntimeConfig获取基础路径：

<template>
  <img :src="`${publicPath}cec-logo-colour-155x70px.png`" alt="Logo">
</template>

<script setup>
const publicPath = useRuntimeConfig().public.baseURL || '/'
</script>

2. onMounted未定义的问题 #

核心原因

组件<script setup>中使用Vue生命周期钩子，但模块未启用Nuxt的自动导入机制，导致API无法被自动识别。

修复步骤

• 显式导入Vue API：在组件中手动导入所需的API：

<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  // 业务逻辑
})
</script>

• 模块中启用自动导入：如果需要模块内组件自动导入Vue API，可以在module.ts的setup函数中添加配置：

nuxt.hook('autoImports:dirs', (dirs) => {
  dirs.push(resolver.resolve('./runtime/composables'))
})

额外验证点 #

• 执行npm pack生成本地包，在测试项目中安装该包，模拟NPM发布后的场景提前排查问题。
• 确认prepack执行后，dist目录包含runtime/components、runtime/assets、runtime/public所有必要文件。

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