package.json 中的重要字段有哪些？exports 如何使用？
package.json 核心字段
{
"name": "my-lib",
"version": "1.0.0",
"description": "描述",
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": { ... },
"files": ["dist"],
"sideEffects": false,
"engines": { "node": ">=18" },
"peerDependencies": { "vue": "^3.0.0" },
"scripts": { ... }
}入口字段
| 字段 | 作用 | 优先级 |
|---|---|---|
main |
CJS 入口 | 基础 |
module |
ESM 入口（打包工具识别） | 高于 main |
browser |
浏览器入口 | 高于 main/module |
types |
TypeScript 类型文件 | — |
exports |
现代入口定义（最高优先级） | 最高 |
exports 字段详解
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"default": "./dist/index.cjs"
},
"./utils": {
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
},
"./styles/*": "./dist/styles/*",
"./package.json": "./package.json"
}
}使用方式：
import lib from 'my-lib' // 匹配 "."
import utils from 'my-lib/utils' // 匹配 "./utils"
import 'my-lib/styles/theme.css' // 匹配 "./styles/*"条件解析顺序：
import → require → defaultexports 的好处
- 子路径访问控制：未列出的路径不可访问（封装内部模块）
- 环境区分：CJS/ESM/浏览器/Deno 不同入口
- 类型安全：
types条件提供类型文件
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"deno": "./dist/index.deno.js",
"browser": "./dist/index.browser.js",
"node": "./dist/index.node.js",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"default": "./dist/index.cjs"
}
}
}version 语义化版本
1.2.3
│ │ │
│ │ └── patch：修复 bug
│ └──── minor：新增功能（向后兼容）
└────── major：破坏性变更版本范围符号：
^1.2.3 → >=1.2.3 <2.0.0 （允许 minor 和 patch 更新，最常用）
~1.2.3 → >=1.2.3 <1.3.0 （只允许 patch 更新）
1.2.3 → 精确版本
>=1.2.3 → 大于等于
* → 任意版本依赖类型
| 类型 | 说明 | 安装位置 |
|---|---|---|
dependencies |
运行时依赖 | 生产 |
devDependencies |
开发依赖 | 开发 |
peerDependencies |
同版本依赖（插件） | 宿主安装 |
optionalDependencies |
可选依赖 | 可选 |
bundleDependencies |
打包依赖 | 内联 |
files 字段
{
"files": ["dist", "README.md"]
}发布到 npm 时只包含这些文件（.npmignore 的反面）。
scripts
{
"scripts": {
"dev": "vite",
"build": "vite build",
"test": "vitest",
"lint": "eslint .",
"prepare": "husky install", // npm install 后自动执行
"prepublishOnly": "npm run build" // 发布前自动构建
}
}发布库最佳实践
{
"name": "my-lib",
"version": "1.0.0",
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"files": ["dist"],
"sideEffects": false,
"engines": { "node": ">=16" },
"peerDependencies": { "vue": "^3.0.0" }
}