Vite构建Vue项目后无法解析本地外部模块lib-model的问题

问题原因 #

开发环境下Vite内置模块解析能力，能识别通过file:引入的裸模块名（如lib-model），但生产构建后，浏览器原生ES模块要求导入路径必须是相对路径（./../）、绝对路径（/）或完整URL，无法直接识别裸模块名，因此抛出报错。

解决方案 #

步骤1：将外部lib打包为浏览器可识别的ES模块 #

你的lib目录目前是TS源码，需要先编译为浏览器能加载的ES模块：

• 进入zproject/lib目录，执行npm init -y初始化npm项目
• 安装TypeScript：npm install typescript --save-dev
• 在lib目录下创建tsconfig.json：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["*.ts"]
}

• 修改lib/package.json，添加编译脚本并指定模块类型：

{
  "name": "lib-model",
  "type": "module",
  "main": "./dist/index.js",
  "scripts": {
    "build": "tsc"
  }
}

• 执行npm run build，生成lib/dist目录的编译产物

步骤2：调整Vue项目的依赖与Vite配置 #

• 更新vue-project/package.json中的依赖指向，确保指向lib的编译产物目录：

"dependencies": {
  "lib-model": "file:../lib"
}

• 重新安装依赖：npm install

步骤3：配置浏览器模块映射（二选一） #

方案A：使用Import Maps（推荐）

在vue-project/index.html的<head>中添加以下代码，告诉浏览器lib-model对应的实际路径：

<script type="importmap">
  {
    "imports": {
      "lib-model": "/lib-model/index.js"
    }
  }
</script>

方案B：通过Vite Rollup配置映射

修改vue-project/vite.config.ts，配置Rollup的外部模块映射：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    rollupOptions: {
      // 标记lib-model为外部模块，不打包进项目
      external: ['lib-model'],
      output: {
        // 将裸模块名映射到服务器上的实际路径
        globals: {
          'lib-model': '/lib-model/index.js'
        }
      }
    }
  }
})

步骤4：部署时同步lib模块 #

将lib/dist目录重命名为lib-model，部署到Nginx服务器的根目录（与Vue项目的dist目录同级），最终服务器目录结构如下：

/var/www/html
├── dist/          # Vue项目构建产物
└── lib-model/     # lib编译后的ES模块

验证 #

重新执行npm run build构建Vue项目，部署后浏览器将能正确解析lib-model模块，不再抛出类型错误。

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