基于Vite 5.2.8构建发布多组件NPM包的结构与导入问题

项目基础信息 #

• Vite版本：5.2.8
• 项目目录结构：

└── ROOT/
    ├── src/
    │   └── utils/
    │       ├── subUtils/
    │       │   └── fixName.ts
    │       ├── log.ts
    │       └── note.ts
    ├── package.json
    ├── tsconfig.json
    └── vite.config.ts

遇到的问题 #

1. dist目录结构不符合预期 #

期望的dist结构：

└── ROOT/
    ├── dist/
    │   ├── log.js
    │   ├── log.d.ts
    │   ├── note.js
    │   ├── note.d.ts
    │   └── subUtils/
    │       ├── fixName.js
    │       └── fixName.d.ts

实际生成的dist结构：

└── ROOT/
    ├── dist/
    │   ├── subUtils/
    │   │   └── fixName.d.ts
    │   ├── utils/
    │   │   ├── log.js
    │   │   ├── note.js
    │   │   └── subUtils/
    │       └── fixName.js
    │   ├── log.d.ts
    │   └── note.d.ts

2. 发布后无法按预期路径导入 #

期望用户安装包后可以这样导入：

import myLog from "test-package/log";
import myNote from "test-package/note";
import myFixName from "test-package/subUtils/fixName";

由于包内包含数百个文件，不想在package.json的exports中逐个配置路径，新增文件时不想重复配置；同时希望支持test-package/subUtils/fixName这类子目录路径导入对应src/utils/subUtils/fixName.ts的文件。

已尝试的方案 #

• 在package.json中设置"main": "dist/"
• 执行npm publish ./dist
• 在vite.config.ts中配置rollup的entries选项

解决方案 #

1. 调整Vite配置，输出正确的dist结构 #

修改vite.config.ts，配置rollup的输入入口为src/utils下的所有文件，同时设置输出目录结构保持和src/utils一致（去掉utils层级）：

import { defineConfig } from 'vite';
import { resolve } from 'path';
import dts from 'vite-plugin-dts';
import glob from 'fast-glob';

// 自动匹配src/utils下所有ts文件，生成入口映射
const entries = Object.fromEntries(
  glob.sync('src/utils/**/*.ts').map(file => [
    file.replace('src/utils/', '').replace('.ts', ''),
    resolve(__dirname, file)
  ])
);

export default defineConfig({
  build: {
    lib: {
      entry: entries,
      formats: ['es'],
      fileName: (format, entryName) => `${entryName}.js`,
    },
    rollupOptions: {
      external: [], // 按需排除外部依赖
    },
  },
  plugins: [
    dts({
      outputDir: 'dist',
      entryRoot: 'src/utils',
      tsConfigFilePath: resolve(__dirname, 'tsconfig.json'),
    }),
  ],
});

先安装依赖支持自动匹配：

npm install fast-glob --save-dev

2. 配置package.json支持通配符导入 #

修改package.json，配置exports和types字段，用通配符匹配所有子路径：

{
  "name": "test-package",
  "type": "module",
  "exports": {
    "./*": "./dist/*.js"
  },
  "typesVersions": {
    "*": {
      "*": ["dist/*.d.ts"]
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "vite build",
    "publish": "npm run build && npm publish"
  }
}

• exports: "./*": "./dist/*.js"：实现test-package/xxx到dist/xxx.js的路径映射
• typesVersions：确保类型文件能被正确解析，对应到dist/xxx.d.ts
• files：指定发布时仅包含dist目录

3. 调整tsconfig.json配置 #

确保tsconfig.json的compilerOptions配置正确：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src/utils", // 以src/utils为根目录，输出时去掉utils层级
    "strict": true,
    "moduleResolution": "bundler",
    "skipLibCheck": true
  },
  "include": ["src/utils/**/*"],
  "exclude": ["node_modules", "dist"]
}

4. 发布包 #

执行命令完成构建与发布：

npm run build
npm publish

这样用户安装后就能按预期路径导入，新增文件时只需在src/utils下添加，Vite会自动打包到dist对应路径，无需修改package.json配置。

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