在 HOW - 编写并发布一个 npm 包模块（含 CLI 工具包开发） 中我们简单介绍过 package.json 文件，并提供了如下示例：
{
// 包的名称
"name": "changelog-tool",
// 包的版本号
"version": "0.5.0",
// 这将显示在NPM搜索结果中
"description": "A CLI tool for manipulating changelogs",
// 这告诉Node这是一个ESM包
// 当然不是严格需要的，如果我们在每个地方都是使用 .mjs
"type": "module",
// 如果需要在编码的时候使用此包中的方法（不是 CLI 中），则需要在这里指定导出的模块入口文件
"main": "index.mjs",
// 将必须的文件才发布到 npm
"files": {
"dist",
"types",
//...
}
"scripts": {
// 运行测试用例
"test": "node --test",
},
// 方便更好的在 npmjs.org 上发现此包
"keywords": [
"changelog",
"markdown"
],
// 作者信息
"author": "Evert Pot (https://evertpot.com/)",
// 做任何你想做的事（MIT协议基本没有约束）
"license": "MIT",
"engine": {
// 警告尚未升级的用户
"node": ">16"
},
"bin": {
// 指定执行文件，当人们安装这个包时，可以通过 `npx changelog` 执行
// 如果全局安装了这个包，就会有一个 `changelog` 命令
"changelog": "./cli.mjs"
},
"devDependencies": {
"@types/node": "^18.11.19",
}
}
除了上述几个 Key Fields，一个完整的开源库还应该设置更多属性。今天我们就来主要介绍一下 package.json。
package.json 文件是 Node.js 项目中的一个关键组件，它包含了项目的元数据，比如项目依赖、脚本、版本等信息。package.json 文件是管理 Node.js 项目的灵活而强大的方式，确保项目的一致性和便于协作。
下面是一个 package.json 文件的示例以及各个字段的解释。
package.json 文件示例{
"name": "example-project",
"version": "1.0.0",
"description": "一个展示 package.json 文件的示例项目",
"main": "index.js",
"scripts": {
"start": "node index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "git+https://github.com/username/example-project.git"
},
"keywords": [
"示例",
"演示",
"node"
],
"author": "Your Name " ,
"license": "ISC",
"bugs": {
"url": "https://github.com/username/example-project/issues"
},
"homepage": "https://github.com/username/example-project#readme",
"dependencies": {
"express": "^4.17.1"
},
"devDependencies": {
"nodemon": "^2.0.7"
}
}
npm run 运行的脚本命令。常见的脚本包括：
"start": 通常用于启动应用程序。"test": 用于运行测试。npm install 安装 package.json 中列出的所有依赖。npm install 添加一个新的依赖，并自动更新 package.json。npm run 执行 scripts 部分定义的脚本。你可以在 scripts 部分定义任何自定义脚本。例如：
"scripts": {
"start": "node index.js",
"test": "echo \"Error: no test specified\" && exit 1",
"build": "webpack --config webpack.config.js",
"lint": "eslint ."
}
这样你就可以运行自定义命令，比如 npm run build 使用 Webpack 打包你的应用程序，或者 npm run lint 使用 ESLint 检查你的代码。
业内有名的组件库 element-plus 其 package.json 文件：
{
"name": "element-plus",
"version": "2.7.1",
"description": "A Component Library for Vue 3",
"keywords": [
"element-plus",
"element",
"component library",
"ui framework",
"ui",
"vue"
],
"homepage": "https://element-plus.org/",
"bugs": {
"url": "https://github.com/element-plus/element-plus/issues"
},
"license": "MIT",
"main": "lib/index.js",
"module": "es/index.mjs",
"types": "es/index.d.ts",
"exports": {
".": {
"types": "./es/index.d.ts",
"import": "./es/index.mjs",
"require": "./lib/index.js"
},
"./global": {
"types": "./global.d.ts"
},
"./es": {
"types": "./es/index.d.ts",
"import": "./es/index.mjs"
},
"./lib": {
"types": "./lib/index.d.ts",
"require": "./lib/index.js"
},
"./es/*.mjs": {
"types": "./es/*.d.ts",
"import": "./es/*.mjs"
},
"./es/*": {
"types": [
"./es/*.d.ts",
"./es/*/index.d.ts"
],
"import": "./es/*.mjs"
},
"./lib/*.js": {
"types": "./lib/*.d.ts",
"require": "./lib/*.js"
},
"./lib/*": {
"types": [
"./lib/*.d.ts",
"./lib/*/index.d.ts"
],
"require": "./lib/*.js"
},
"./*": "./*"
},
"unpkg": "dist/index.full.js",
"jsdelivr": "dist/index.full.js",
"repository": {
"type": "git",
"url": "git+https://github.com/element-plus/element-plus.git"
},
"publishConfig": {
"access": "public"
},
"style": "dist/index.css",
"sideEffects": [
"dist/*",
"theme-chalk/**/*.css",
"theme-chalk/src/**/*.scss",
"es/components/*/style/*",
"lib/components/*/style/*"
],
"peerDependencies": {
"vue": "^3.2.0"
},
"dependencies": {
"@ctrl/tinycolor": "^3.4.1",
"@element-plus/icons-vue": "^2.3.1",
"@floating-ui/dom": "^1.0.1",
"@popperjs/core": "npm:@sxzz/popperjs-es@^2.11.7",
"@types/lodash": "^4.14.182",
"@types/lodash-es": "^4.17.6",
"@vueuse/core": "^9.1.0",
"async-validator": "^4.2.5",
"dayjs": "^1.11.3",
"escape-html": "^1.0.3",
"lodash": "^4.17.21",
"lodash-es": "^4.17.21",
"lodash-unified": "^1.0.2",
"memoize-one": "^6.0.0",
"normalize-wheel-es": "^1.2.0"
},
"devDependencies": {
"@types/node": "*",
"csstype": "^2.6.20",
"vue": "^3.2.37",
"vue-router": "^4.0.16"
},
"vetur": {
"tags": "tags.json",
"attributes": "attributes.json"
},
"web-types": "web-types.json",
"browserslist": [
"> 1%",
"not ie 11",
"not op_mini all"
],
"gitHead": "b0ce448b4dc7c8981ed73bd2554f4dbbe05d1446"
}
在 package.json 文件中，main 和 module 字段用于指定项目的入口文件，但它们有不同的用途和作用范围，主要与模块系统的选择有关。
main 字段指定了 Node.js 项目入口文件的路径。它告诉 Node.js 在使用 require() 函数引入模块时应该加载哪个文件。如果没有指定 main 字段，Node.js 默认会寻找项目根目录下的 index.js 文件。
示例
{
"main": "index.js"
}
在上面的例子中，如果你的项目被其他项目引入，Node.js 会从 index.js 文件开始加载。
module 字段module 字段用于指定 ECMAScript 模块（ESM）的入口文件路径。它主要面向现代 JavaScript 环境，如使用 import 语句的前端项目或支持 ESM 的 Node.js 项目。这个字段提供了一个入口点，允许 JavaScript 运行时和打包工具（如 webpack、rollup）以 ESM 格式加载模块。
示例
{
"module": "index.mjs"
}
在这个例子中，当你的项目被打包工具或支持 ESM 的环境引入时，它会从 index.mjs 文件开始加载。
一个完整的 package.json 文件可能同时包含 main 和 module 字段，以便兼容 CommonJS 和 ESM 模块系统。
{
"name": "example-project",
"version": "1.0.0",
"description": "一个展示 package.json 文件的示例项目",
"main": "index.js",
"module": "index.mjs",
"scripts": {
"start": "node index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"express": "^4.17.1"
},
"devDependencies": {
"nodemon": "^2.0.7"
}
}
通过同时定义 main 和 module 字段，可以确保你的包在不同的模块系统中都能被正确加载和使用。这对于兼容性和灵活性非常重要，尤其是在需要支持多种环境的库或工具中。
types 字段（或 typings）用于指定 TypeScript 类型定义文件的路径。它通常用于那些用 JavaScript 编写的包，并且希望提供 TypeScript 类型支持。这个字段指向一个包含 TypeScript 声明的文件，通常是 .d.ts 文件。
假设你有一个项目，其中包含一个 TypeScript 类型定义文件 index.d.ts，你的 package.json 文件可以这样配置：
{
"name": "example-project",
"version": "1.0.0",
"description": "一个展示 package.json 文件的示例项目",
"main": "index.js",
"module": "index.mjs",
"types": "index.d.ts",
"scripts": {
"start": "node index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"express": "^4.17.1"
},
"devDependencies": {
"nodemon": "^2.0.7"
}
}
假设你的项目的主要功能在 index.js 文件中实现，你可以创建一个 index.d.ts 文件来描述这些功能的类型：
index.js
function greet(name) {
return `Hello, ${name}!`;
}
module.exports = {
greet
};
index.d.ts
export function greet(name: string): string;
当你发布带有类型定义文件的包时，TypeScript 项目可以直接使用你的类型定义文件，无需额外配置。这使得你的包对使用 TypeScript 的开发者更加友好。
styles 字段（虽然不属于官方的 package.json 规范）有时会出现在某些前端项目中，用于指定项目的主要样式表文件路径。这个字段主要用于与构建工具和打包工具（如 webpack）集成，方便这些工具找到并处理样式文件。
假设你有一个项目，其中包含一个主要的 CSS 文件 dist/index.css，你的 package.json 文件可以这样配置：
{
"name": "example-project",
"version": "1.0.0",
"description": "一个展示 package.json 文件的示例项目",
"main": "index.js",
"module": "index.mjs",
"types": "index.d.ts",
"styles": "dist/index.css",
"scripts": {
"start": "node index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"express": "^4.17.1"
},
"devDependencies": {
"nodemon": "^2.0.7"
}
}
styles 字段，以便自动加载和处理样式文件。styles 字段可以帮助开发者快速找到并加载样式文件。这在一些组件库提供按需加载能力时常见。
在 package.json 文件中，dependencies、devDependencies 和 peerDependencies 是用于管理和声明项目所需依赖的三种不同方式。它们的主要区别在于依赖的用途和安装时机。
dependencies 字段列出了项目在生产环境中运行所需的包。换句话说，这些依赖是项目在正常运行时必需的。安装项目时，npm install 会自动安装这些依赖。
{
"dependencies": {
"express": "^4.17.1",
"lodash": "^4.17.21"
}
}
devDependencies 字段列出了项目在开发阶段所需的包。这些依赖在项目构建、测试或开发时使用，但在生产环境中不需要。安装项目时，如果使用 npm install --production 或 NODE_ENV=production npm install，则不会安装这些依赖。
{
"devDependencies": {
"eslint": "^7.32.0",
"jest": "^27.0.6"
}
}
peerDependencies 字段用来声明项目对某个包的依赖，但是该包应由项目的使用者（即最终用户）来安装。
这在创建插件或库时特别有用，确保依赖的版本与最终使用项目的版本兼容。例如，一个 React 组件库可能会将 react 和 react-dom 声明为 peerDependencies，以确保使用该库的项目使用的是正确版本的 react。
{
"peerDependencies": {
"react": "^17.0.0",
"react-dom": "^17.0.0"
}
}
peerDependencies 字段的主要作用是声明项目对某些依赖包的兼容性要求，但并不直接安装这些依赖包。它通常用于插件或库，以确保这些插件或库与宿主应用的依赖版本一致。
理解 peerDependencies 可以通过以下几个方面来更清晰：
当你的库或插件需要与某个主项目共享依赖时，peerDependencies 可以声明这些共享依赖的版本范围。例如，一个 React 组件库可能需要使用者项目中的 react 和 react-dom，但不希望自己安装这些依赖，因为它们应该由使用者项目来管理和安装。
通过使用 peerDependencies，可以避免安装多个版本的同一个包，从而减少版本冲突的风险。如果每个库都各自安装自己的 react 版本，可能会导致不同版本的 react 互相冲突，从而引发错误。
假设你在开发一个 React 组件库：
package.json
{
"name": "my-react-library",
"version": "1.0.0",
"peerDependencies": {
"react": "^17.0.0",
"react-dom": "^17.0.0"
}
}
使用者项目中安装你的库时，npm 会发出警告，提示需要安装特定版本的 react 和 react-dom：
npm install my-react-library
如果用户项目中没有安装 react 或 react-dom，或安装的版本与 peerDependencies 中指定的不兼容，npm 会显示警告信息。
例如，如果用户的项目中安装了 React 16 而不是 React 17，运行 npm install 时可能会看到这样的警告：
npm WARN my-react-library@1.0.0 requires a peer of react@^17.0.0 but none is installed. You must install peer dependencies yourself.
用户需要确保其项目中的依赖版本与 peerDependencies 中声明的版本兼容。通常这意味着用户需要更新其项目中的相关依赖版本：
npm install react@^17.0.0 react-dom@^17.0.0
exports 字段是在 Node.js 12 及其以上版本中引入的，用于指定模块的导出路径和条件导出。
它提供了一种更精细的方式来定义项目中的入口点和模块分发，支持不同的模块系统（如 CommonJS 和 ES Module）以及不同的运行环境（如浏览器和 Node.js）。
exportsexports 字段示例假设你的项目结构如下：
my-package/
├── package.json
├── index.js
├── index.mjs
└── lib/
├── feature.cjs
├── feature.mjs
└── feature.js
你可以在 package.json 中使用 exports 字段来定义不同环境下的导出：
{
"name": "my-package",
"version": "1.0.0",
"main": "index.js",
"module": "index.mjs",
"exports": {
".": {
"require": "./index.js",
"import": "./index.mjs"
},
"./feature": {
"require": "./lib/feature.cjs",
"import": "./lib/feature.mjs",
"default": "./lib/feature.js"
}
}
}
".": 代表包的根路径，定义包的主要入口点。
"require": 指定 CommonJS 模块系统下的入口点。"import": 指定 ES Module 模块系统下的入口点。"./feature": 定义 my-package/feature 的导出路径。
"require": 使用 CommonJS 模块系统时，导出 ./lib/feature.cjs 文件。"import": 使用 ES Module 模块系统时，导出 ./lib/feature.mjs 文件。"default": 其他情况使用 ./lib/feature.js 文件。可以为不同的条件提供更多的导出路径：
{
"exports": {
".": {
"browser": {
"import": "./index.browser.mjs",
"require": "./index.browser.cjs"
},
"node": {
"import": "./index.node.mjs",
"require": "./index.node.cjs"
},
"default": "./index.js"
},
"./feature": {
"browser": {
"import": "./lib/feature.browser.mjs",
"require": "./lib/feature.browser.cjs"
},
"node": {
"import": "./lib/feature.node.mjs",
"require": "./lib/feature.node.cjs"
},
"default": "./lib/feature.js"
}
}
}
exports 字段统一管理。通过合理使用 exports 字段，可以使你的 Node.js 包在现代 JavaScript 生态系统中更具适应性和灵活性。
unpkg 和 jsDelivr 都是用于提供前端资源（如 JavaScript、CSS、图像等）的 CDN（内容分发网络）服务，使得开发者可以方便地在项目中引用这些资源而无需自行托管。
{
"unpkg": "dist/umd/package.min.js"
}
这个字段告诉 unpkg CDN，当有人访问该包时，应该返回 dist/umd/package.min.js 文件。
unpkg 是一个快速、稳定的 CDN，用于托管 npm 中的开源包。它允许你通过简单地提供包名和版本号来直接引用 npm 包中的文件，而无需安装这些包或手动下载文件。通过 unpkg，你可以在浏览器中直接访问 npm 包中的任何文件。
例如，如果你想在项目中使用 React，你可以通过以下方式引用 React 的主要文件：
<script src="https://unpkg.com/react@17/umd/react.production.min.js">script>
<script src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js">script>
{
"jsdelivr": "dist/umd/package.min.js"
}
这个字段告诉 jsDelivr CDN，当有人访问该包时，应该返回 dist/umd/package.min.js 文件。
jsDelivr 是另一个流行的 CDN，提供了更多的功能和定制选项。它支持各种前端资源，包括 JavaScript 库、CSS 框架、图像、字体等。jsDelivr 的优点之一是它有多个节点，因此可以提供更快的下载速度和更高的可用性。
与 unpkg 类似，你可以使用 jsDelivr 来直接引用各种开源资源，而无需自行下载和托管。例如，你可以通过以下方式引用 jQuery：
<script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js">script>
无论你选择哪个 CDN，它们都可以帮助你更轻松地管理前端资源，加速网站加载速度，并提高开发效率。
publishConfig 字段是 package.json 文件中的一个配置项，用于指定发布 npm 包时的额外设置。
通过 publishConfig 字段，你可以设置一些发布相关的配置，例如发布时的访问权限、发布时所使用的注册表等。
以下是一个典型的 publishConfig 字段的示例：
{
"name": "my-package",
"version": "1.0.0",
"description": "A sample package",
"main": "index.js",
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/"
}
}
在这个示例中，publishConfig 字段指定了两个选项：
access: 指定了发布时的访问权限。在这个例子中，设置为 "public" 表示发布后的包是公共的，所有人都可以访问。registry: 指定了发布时所使用的 npm 注册表的 URL。在这个例子中，设置为 "https://registry.npmjs.org/" 表示发布到 npm 公共注册表。access 设置为 "restricted"，只允许有权限的用户访问。registry 字段来指定发布时所使用的注册表的 URL。publishConfig 字段通常用于在发布 npm 包时自定义配置，但它并不是必需的。如果你没有特殊的需求，可以不用设置它。publishConfig。理解 publishConfig 字段的用途和配置选项，可以帮助你更好地管理和发布 npm 包。
sideEffects 是一个用于告知 webpack 和其他模块打包工具模块是否有副作用（side effects）的字段，出现在模块的 package.json 文件中。副作用是指模块执行时，不仅仅是导出一个值，而是会执行一些额外的操作，例如修改全局变量、执行某些代码等。
sideEffects对于纯粹的 JavaScript 模块，大部分情况下，模块导入后只是为了获取导出的值，而不会对环境产生任何副作用。然而，一些模块可能会包含副作用，这些副作用可能会影响到整个应用程序的行为，甚至影响到其他模块。在模块打包时，如果可以确定某个模块没有副作用，打包工具就可以进行更多的优化，例如删除未使用的代码、提取公共代码等。而如果某个模块包含了副作用，打包工具则需要谨慎处理，以避免意外行为。
有关模块包含副作用的内容可以阅读 WHAT - Webpack 详解系列（七）。
Webpack 4 中新增了一个 sideEffects 特性，它允许我们通过配置标识我们的代码是否有副作用，从而提供更大的压缩空间。模块的副作用指的是：模块执行的时候除了导出成员，是否还做了其他的事情。这个特性一般只有我们去开发一个 npm 模块时才会用到。以自定义 npm 项目为例，那此时 Webpack 在打包某个模块之前，会先检查这个模块所属的 package.json 中的 sideEffects 标识，以此来判断这个模块是否有副作用，如果没有副作用的话，这些没用到的模块就不再被打包。
sideEffects 的取值sideEffects 字段的取值可以是以下三种形式之一：
false: 表示模块没有副作用。这意味着打包工具可以安全地进行一些额外的优化。true: 表示模块具有副作用。在打包时，打包工具将假定该模块具有副作用，并相应地处理它。以下是一个 sideEffects 字段的示例：
{
"name": "my-package",
"version": "1.0.0",
"description": "A sample package",
"main": "index.js",
"sideEffects": ["*.css", "*.scss", "*.less"]
}
在这个示例中，sideEffects 字段告知打包工具，在打包时应该考虑所有的 .css、.scss 和 .less 文件，因为它们可能包含一些样式文件的副作用。
sideEffects 设置为 false，因为大多数模块都不会有副作用。sideEffects 字段，或者设置为 true，以确保不会因为错误的优化而导致意外行为。通过正确地设置 sideEffects 字段，可以帮助你更好地管理和优化你的模块打包过程。
browserslist 是一个用于指定项目目标浏览器的字段，出现在项目根目录下的 package.json 文件中。它告知前端工具（例如 Autoprefixer、Babel、PostCSS 等）需要支持哪些浏览器版本，以便自动添加适当的 CSS 前缀或将 JavaScript 代码转换成兼容性更好的形式。
browserslistWeb 开发中，不同的浏览器对于一些 CSS 属性和 JavaScript 特性的支持程度有所差异。为了确保项目在不同浏览器中的兼容性，开发者通常需要根据项目需求选择目标浏览器，并进行相应的兼容性处理。
browserslist 的出现简化了这个过程，使得开发者只需在项目中设置一次目标浏览器列表，然后前端工具就可以根据这个列表自动进行相应的处理，大大提高了开发效率。
browserslist 的使用你可以在 package.json 文件中的 browserslist 字段中指定目标浏览器的列表，也可以通过 .browserslistrc 文件或者 browserslist 配置文件来配置。
示例 browserslist 配置：
"browserslist": [
"last 2 versions",
"> 1%",
"IE 11"
],
这个配置表示项目的目标浏览器为：
"browserslist": [
"> 1%",
"not ie 11",
"not op_mini all"
],
这个配置表示项目的目标浏览器为：
browserslist 配置自动添加 CSS 前缀，以确保样式在目标浏览器中的兼容性。browserslist 配置自动将 ES6+ 的 JavaScript 代码转换成向下兼容的代码，以确保在目标浏览器中的兼容性。browserslist 配置，以确保项目始终针对最新的浏览器进行优化。通过合理配置 browserslist，可以帮助开发者更轻松地管理项目的浏览器兼容性，提高开发效率。