如何为自研React组件库包启用二级路径导入功能

1. 调整图标包目录结构 #

首先保证@my-lib/icon包的目录结构和你要暴露的导入路径匹配，参考结构如下：

your-lerna-monorepo/
└── packages/
    └── icon/
        ├── src/
        │   ├── plus.tsx          # PlusIcon 单独组件文件
        │   ├── minus.tsx         # MinusIcon 单独组件文件
        │   ├── close.tsx         # 其他图标组件
        │   └── index.ts          # 原有全量导出入口
        ├── package.json
        └── 构建配置文件（rollup/tsup/esbuild 配置等）

每个图标单独存为一个文件，文件名即为你期望用户导入的路径后缀，比如plus.tsx对应@my-lib/icon/plus。

2. 配置 package.json 子路径映射 #

这一步是实现用户零配置直接导入的核心，依赖 Node 以及主流前端构建工具（webpack5+/Vite/Rollup 等）原生支持的exports和typesVersions字段，在图标包的package.json中添加如下配置：

{
  "name": "@my-lib/icon",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts",
  // 子路径导出规则
  "exports": {
    ".": "./dist/index.js",
    // 图标量少可以逐个配置
    "./plus": "./dist/plus.js",
    "./minus": "./dist/minus.js",
    // 图标量多直接用通配符匹配所有路径
    "./*": "./dist/*.js"
  },
  // 同步配置TS类型子路径映射，保证类型提示正常
  "typesVersions": {
    "*": {
      "plus": ["./dist/plus.d.ts"],
      "minus": ["./dist/minus.d.ts"],
      // 同样支持通配符
      "*": ["./dist/*.d.ts"]
    }
  }
}

兼容说明：如果需要支持 webpack4 等旧版本构建工具，你需要在构建完成后，在图标包的根目录生成对应路径的转发文件，比如plus.js内容为module.exports = require('./dist/plus.js')，plus.d.ts内容为export * from './dist/plus'，旧工具会自动识别根目录下的文件路径。

3. 调整构建配置输出单文件 #

修改图标包的构建配置，将每个图标组件单独编译输出到dist目录，而非全部打包到单个index.js中。
以tsup构建为例，配置示例如下：

// icon 包根目录 tsup.config.ts
import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/**/*.tsx', '!src/**/*.test.tsx'], // 所有图标文件作为独立入口
  format: ['esm', 'cjs'], // 同时输出ES模块和CommonJS格式
  dts: true, // 自动生成类型声明文件
  outDir: 'dist',
  clean: true
})

如果使用 Rollup 或其他构建工具，逻辑一致：将每个图标文件设为独立入口，单独输出编译后的文件和对应类型声明。

4. 本地验证效果 #

可以通过npm link或yalc在本地测试导入逻辑：

• 进入图标包目录执行npm link
• 新建测试 React 项目执行npm link @my-lib/icon
• 测试import PlusIcon from '@my-lib/icon/plus'写法，确认组件可正常渲染、TS类型提示正常、构建产物中没有未使用的其他图标代码即可。

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