使用npm link时Vue项目在Vite中的路径别名问题

操作步骤 #

• 在项目A目录执行：

  npm link
  

• 在项目B目录执行：

  npm link rc-webcomponents
  

• 在项目B的main.js中添加：

  import 'rc-webcomponents'
  

问题现象 #

运行npm run dev时出现依赖解析错误，提示项目A中以@开头的路径无法解析。尝试将Vite配置中别名从对象形式改为数组形式后，问题依旧。

错误详情 #

Error: The following dependencies are imported but could not be resolved:

  @/polyfill (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/sass/reset.scss (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/plugins/rcwc (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/composables/RcwcObject (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/utils/relativeDate (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/locales (imported by M:/Dev/RC-WebComponents/src/index.ts)
  @/composables/customHtmlElement (imported by M:/Dev/RC-WebComponents/src/index.ts)

Are they installed?
    at file:///M:/Dev/localtests/my-vue-app3/node_modules/vite/dist/node/chunks/dep-mCdpKltl.js:50346:15
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async file:///M:/Dev/localtests/my-vue-app3/node_modules/vite/dist/node/chunks/dep-mCdpKltl.js:49851:26

原Vite别名配置（对象形式） #

export function defineSharedConfig(cfg:UserConfig): UserConfig {
    return defineConfig(
        {
            resolve: {
                ...(cfg.resolve || {}),
                alias: {
                    "@": fileURLToPath(new URL("./src", import.meta.url)),
                    vue: fileURLToPath(new URL("node_modules/@vue/compat", import.meta.url)),
                    "~rc-webcomponents": fileURLToPath(new URL("./src", import.meta.url)),
                    "~vue2-datepicker": fileURLToPath(new URL("node_modules/vue2-datepicker", import.meta.url)),
                    ...(cfg.resolve?.alias || {}),
                },
            },
    }

}

修改后的Vite别名配置（数组形式） #

alias: [
    { find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) },
    { find: 'vue', replacement: fileURLToPath(new URL('node_modules/@vue/compat', import.meta.url)) },
    { find: '~rc-webcomponents', replacement: fileURLToPath(new URL('./src', import.meta.url)) },
    { find: '~vue2-datepicker', replacement: fileURLToPath(new URL('node_modules/vue2-datepicker', import.meta.url)) },
],

解决方法 #

1. 让项目A的别名在外部可解析 #

Vite的别名默认仅对当前项目生效，npm link后项目B无法识别项目A内部的@别名，因为项目A的源码未经过编译转换别名。可在项目A中做以下处理：

• 确保package.json添加type: "module"，同时tsconfig.json的compilerOptions.paths配置与Vite别名完全匹配
• 使用vite-plugin-lib-inject-css等插件，打包时将别名路径转换为相对路径，再通过npm link使用打包后的产物

2. 在项目B中手动映射项目A的@别名 #

若不想打包项目A，可在项目B的vite.config.mts中添加项目A的@别名指向：

resolve: {
  alias: [
    // 保留原有别名
    { 
      find: '@', 
      replacement: fileURLToPath(new URL('../RC-WebComponents/src', import.meta.url)) 
    },
  ]
}

注意根据实际项目位置调整路径，确保指向项目A的src目录。

3. 替代npm link的方案（推荐） #

直接在项目B中通过本地路径引入项目A，同时配置Vite跳过预构建：

• 在项目B的package.json中添加依赖：

  "dependencies": {
    "rc-webcomponents": "file:../RC-WebComponents"
  }
  

• 执行npm install后，在项目B的vite.config.mts中添加：

  export default defineConfig({
    optimizeDeps: {
      exclude: ['rc-webcomponents']
    }
  })
  

这种方式下Vite会直接解析项目A的源码并应用其内部的别名配置。

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