如何自定义NPM包的导入路径？实现无dist前缀的分模块导入

核心思路 #

借助npm标准的exports字段映射导入路径，配合Webpack多入口打包调整dist目录结构，同时处理TypeScript类型解析，实现@package/name/base这类简洁路径导入。

步骤1：调整源码与目标dist结构 #

先拆分模块入口，确保构建后目录对应：

• 源码侧：给需要拆分的模块单独设置入口文件，比如src/components/base/index.ts（导出基础组件）、src/components/icons/index.ts（导出图标组件），保留src/index.ts作为全量导出入口
• 构建后dist侧：要生成dist/base/index.js、dist/base/index.d.ts、dist/icons/index.js、dist/icons/index.d.ts，同时保留根目录的dist/index.js和dist/index.d.ts

步骤2：修改Webpack配置实现多入口打包 #

调整entry和output配置，让每个子模块打包到对应dist子目录：

const path = require('path');

module.exports = {
  entry: {
    main: './src/index.ts', // 全量导出入口
    base: './src/components/base/index.ts',
    icons: './src/components/icons/index.ts'
  },
  output: {
    filename: '[name]/index.js', // 每个入口打包到对应子目录的index.js
    path: path.resolve(__dirname, 'dist'),
    library: {
      type: 'umd', // 兼容CommonJS/ESModule等多种模块规范
      name: '@package/name'
    },
    clean: true // 构建前自动清空dist
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js']
  }
};

步骤3：配置package.json映射导入路径 #

通过exports字段定义路径映射，用typesVersions处理TypeScript类型关联：

{
  "name": "@package/name",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": "./dist/index.js", // 全量导入@package/name
    "./base": "./dist/base/index.js", // 导入@package/name/base
    "./icons": "./dist/icons/index.js", // 导入@package/name/icons
    "./base/*": "./dist/base/*.js", // 支持子路径如@package/name/base/Button
    "./icons/*": "./dist/icons/*.js" // 支持子路径如@package/name/icons/CloseIcon
  },
  "typesVersions": {
    "*": {
      "base": ["dist/base/index.d.ts"],
      "icons": ["dist/icons/index.d.ts"],
      "base/*": ["dist/base/*.d.ts"],
      "icons/*": ["dist/icons/*.d.ts"]
    }
  }
}

步骤4：验证TypeScript配置 #

确保tsconfig.json生成正确的类型文件：

{
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true, // 自动生成d.ts类型文件
    "declarationMap": true,
    "module": "ESNext",
    "target": "ES2015",
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

常见问题排查 #

• 类型报错：检查typesVersions路径和exports是否完全对应，确认dist目录下已生成对应d.ts文件
• 路径映射失效：确保Node.js版本>=12.16、npm>=7/yarn>=2（支持exports字段），检查package.json的exports语法是否正确
• 子目录无打包文件：核对Webpack entry的文件路径是否正确，output的filename配置是否为[name]/index.js

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