skillhub-179-ts-library/setup/exports.md

Package Exports（包导出）

Basic Single Entry（基本单入口）

{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.mts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.mts",
  "sideEffects": false,
  "files": ["dist"]
}

Multiple Entry Points（多入口点）

{
  "exports": {
    ".": {
      "types": "./dist/index.d.mts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils.d.mts",
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    },
    "./*": "./dist/*"
  }
}

Plugin Entry Pattern (unplugin-*)（插件入口模式，unplugin-*）

{
  "exports": {
    ".": {
      "types": "./dist/index.d.mts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./vite": {
      "types": "./dist/vite.d.mts",
      "import": "./dist/vite.mjs",
      "require": "./dist/vite.cjs"
    },
    "./webpack": {
      "types": "./dist/webpack.d.mts",
      "import": "./dist/webpack.mjs",
      "require": "./dist/webpack.cjs"
    },
    "./nuxt": {
      "types": "./dist/nuxt.d.mts",
      "import": "./dist/nuxt.mjs",
      "require": "./dist/nuxt.cjs"
    }
  }
}

Environment-Aware Exports（环境感知导出）

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "node": {
        "import": { "production": "./dist/index.prod.mjs", "development": "./dist/index.mjs" },
        "require": { "production": "./dist/index.prod.cjs", "development": "./dist/index.cjs" }
      },
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

typesVersions Fallback（typesVersions 回退）

针对不支持 exports 的旧版 TypeScript：

{
  "typesVersions": {
    "*": {
      "*": ["./dist/*", "./*"]
    }
  }
}

Field Reference（字段参考）

字段	用途
exports	现代入口点（Node 12.7+）
main	针对旧版打包工具的 CJS 回退
module	针对打包工具的 ESM 回退
types	TypeScript 回退
sideEffects	false 启用 tree-shaking
files	发布到 npm 的文件列表

Condition Order（条件顺序）

顺序很重要！最具体的放在最前面：

{
  ".": {
    "types": "...",      // 始终放在第一位
    "import": "...",     // ESM
    "require": "..."     // CJS 回退
  }
}

Peer Dependencies（对等依赖）

消费者必须提供的外部依赖：

{
  "peerDependencies": {
    "vue": "^3.0.0"
  },
  "peerDependenciesMeta": {
    "vue": { "optional": true }
  }
}

Package Validation（包验证）

# 检查导出配置是否正确
pnpm dlx publint
pnpm dlx @arethetypeswrong/cli

将以上步骤加入 CI 以实现持续验证。