WHAT - package.json 解释

一、前言
二、介绍
- [2.1 `package.json` 文件示例](#2.1 package.json 文件示例)
- [2.2 关键字段](#2.2 关键字段)
- [2.3 常用命令](#2.3 常用命令)
- [2.4 自定义脚本](#2.4 自定义脚本)
[三、element-plus 完整示例](#三、element-plus 完整示例)
- [3.1 main 和 module](#3.1 main 和 module)
- - [1. main 字段](#1. main 字段)
  - [2. `module` 字段](#2. module 字段)
  - [3. 综合示例](#3. 综合示例)
- [3.2 types](#3.2 types)
- - [1. 示例](#1. 示例)
  - [2. TypeScript 类型定义文件的作用](#2. TypeScript 类型定义文件的作用)
  - [3. 类型定义文件示例](#3. 类型定义文件示例)
  - [4. 发布带有类型定义的包](#4. 发布带有类型定义的包)
- [3.3 styles](#3.3 styles)
- - [1. 示例](#1. 示例)
  - [2. 用途](#2. 用途)
- [3.4 peerDependencies](#3.4 peerDependencies)
- - [1. dependencies](#1. dependencies)
  - - 示例
  - [2. devDependencies](#2. devDependencies)
  - - 示例
  - [3. peerDependencies](#3. peerDependencies)
  - - 示例
    - 进一步理解
- [3.5 exports](#3.5 exports)
- - [为什么使用 `exports`](#为什么使用 exports)
  - [`exports` 字段示例](#exports 字段示例)
  - 解释
  - 更多复杂示例
  - 使用场景
- [3.6 unpkg 和 jsdelivr](#3.6 unpkg 和 jsdelivr)
- [3.7 publishConfig](#3.7 publishConfig)
- [3.8 sideEffects](#3.8 sideEffects)
- - [为什么需要 `sideEffects`](#为什么需要 sideEffects)
  - [`sideEffects` 的取值](#sideEffects 的取值)
  - 示例
  - 使用场景
  - 注意事项
- [3.9 browserslist](#3.9 browserslist)
- - [为什么需要 `browserslist`](#为什么需要 browserslist)
  - [`browserslist` 的使用](#browserslist 的使用)
  - 使用场景
  - 注意事项

一、前言

在 HOW - 编写并发布一个 npm 包模块（含 CLI 工具包开发）中我们简单介绍过 package.json 文件，并提供了如下示例：

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 文件的示例以及各个字段的解释。

2.1 `package.json` 文件示例

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 <[email protected]>",
  "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"
  }
}

2.2 关键字段

name: 项目的名称，应为小写字母，可以包含连字符和下划线。
version : 项目的当前版本，遵循语义化版本控制（semver）。
description: 项目的简短描述。
main: 应用程序的入口文件（通常是主 JavaScript 文件）。
scripts : 定义一组可以通过 npm run <script-name> 运行的脚本命令。常见的脚本包括：
- "start": 通常用于启动应用程序。
- "test": 用于运行测试。
repository: 关于源代码托管仓库的信息。
keywords: 一个字符串数组，帮助人们在搜索时找到你的项目。
author: 项目作者的名字和联系方式。
license: 项目的许可证。
bugs: 报告问题的地址。
homepage: 项目的主页 URL。
dependencies: 一个对象，指定了项目的运行时依赖及其版本。
devDependencies: 一个对象，指定了项目的开发时依赖，仅在开发过程中需要。

2.3 常用命令

安装依赖 : 运行 npm install 安装 package.json 中列出的所有依赖。
添加依赖 : 运行 npm install <package-name> 添加一个新的依赖，并自动更新 package.json。
运行脚本 : 运行 npm run <script-name> 执行 scripts 部分定义的脚本。

2.4 自定义脚本

你可以在 scripts 部分定义任何自定义脚本。例如：

json 复制代码

"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 完整示例

业内有名的组件库 element-plus 其 package.json 文件：

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"
}

3.1 main 和 module

在 package.json 文件中，main 和 module 字段用于指定项目的入口文件，但它们有不同的用途和作用范围，主要与模块系统的选择有关。

1. main 字段

main 字段指定了 Node.js 项目入口文件的路径。它告诉 Node.js 在使用 require() 函数引入模块时应该加载哪个文件。如果没有指定 main 字段，Node.js 默认会寻找项目根目录下的 index.js 文件。

示例

json 复制代码

{
  "main": "index.js"
}

在上面的例子中，如果你的项目被其他项目引入，Node.js 会从 index.js 文件开始加载。

2. `module` 字段

module 字段用于指定 ECMAScript 模块（ESM）的入口文件路径。它主要面向现代 JavaScript 环境，如使用 import 语句的前端项目或支持 ESM 的 Node.js 项目。这个字段提供了一个入口点，允许 JavaScript 运行时和打包工具（如 webpack、rollup）以 ESM 格式加载模块。

示例

json 复制代码

{
  "module": "index.mjs"
}

在这个例子中，当你的项目被打包工具或支持 ESM 的环境引入时，它会从 index.mjs 文件开始加载。

3. 综合示例

一个完整的 package.json 文件可能同时包含 main 和 module 字段，以便兼容 CommonJS 和 ESM 模块系统。

json 复制代码

{
  "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 字段，可以确保你的包在不同的模块系统中都能被正确加载和使用。这对于兼容性和灵活性非常重要，尤其是在需要支持多种环境的库或工具中。

3.2 types

types 字段（或 typings）用于指定 TypeScript 类型定义文件的路径。它通常用于那些用 JavaScript 编写的包，并且希望提供 TypeScript 类型支持。这个字段指向一个包含 TypeScript 声明的文件，通常是 .d.ts 文件。

1. 示例

假设你有一个项目，其中包含一个 TypeScript 类型定义文件 index.d.ts，你的 package.json 文件可以这样配置：

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"
  }
}

2. TypeScript 类型定义文件的作用

提供类型支持: 当使用你的库时，TypeScript 编译器可以引用这个类型定义文件，提供类型检查和代码补全。
提高开发体验: 使用 TypeScript 类型定义文件可以使你的库在 TypeScript 项目中更容易使用，因为开发者可以获得更好的代码提示和类型检查。

3. 类型定义文件示例

假设你的项目的主要功能在 index.js 文件中实现，你可以创建一个 index.d.ts 文件来描述这些功能的类型：

index.js

javascript 复制代码

function greet(name) {
  return `Hello, ${name}!`;
}
module.exports = {
  greet
};

index.d.ts

typescript 复制代码

export function greet(name: string): string;

4. 发布带有类型定义的包

当你发布带有类型定义文件的包时，TypeScript 项目可以直接使用你的类型定义文件，无需额外配置。这使得你的包对使用 TypeScript 的开发者更加友好。

3.3 styles

styles 字段（虽然不属于官方的 package.json 规范）有时会出现在某些前端项目中，用于指定项目的主要样式表文件路径。这个字段主要用于与构建工具和打包工具（如 webpack）集成，方便这些工具找到并处理样式文件。

1. 示例

假设你有一个项目，其中包含一个主要的 CSS 文件 dist/index.css，你的 package.json 文件可以这样配置：

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"
  }
}

2. 用途

构建工具集成 : 某些构建工具（如 webpack、rollup）或插件可能会读取 styles 字段，以便自动加载和处理样式文件。
模块化 CSS : 当你的包被其他项目引用时，styles 字段可以帮助开发者快速找到并加载样式文件。

这在一些组件库提供按需加载能力时常见。

3.4 peerDependencies

在 package.json 文件中，dependencies、devDependencies 和 peerDependencies 是用于管理和声明项目所需依赖的三种不同方式。它们的主要区别在于依赖的用途和安装时机。

1. dependencies

dependencies 字段列出了项目在生产环境中运行所需的包。换句话说，这些依赖是项目在正常运行时必需的。安装项目时，npm install 会自动安装这些依赖。

示例

json 复制代码

{
  "dependencies": {
    "express": "^4.17.1",
    "lodash": "^4.17.21"
  }
}

2. devDependencies

devDependencies 字段列出了项目在开发阶段所需的包。这些依赖在项目构建、测试或开发时使用，但在生产环境中不需要。安装项目时，如果使用 npm install --production 或 NODE_ENV=production npm install，则不会安装这些依赖。

示例

json 复制代码

{
  "devDependencies": {
    "eslint": "^7.32.0",
    "jest": "^27.0.6"
  }
}

3. peerDependencies

peerDependencies 字段用来声明项目对某个包的依赖，但是该包应由项目的使用者（即最终用户）来安装。

这在创建插件或库时特别有用，确保依赖的版本与最终使用项目的版本兼容。例如，一个 React 组件库可能会将 react 和 react-dom 声明为 peerDependencies，以确保使用该库的项目使用的是正确版本的 react。

示例

json 复制代码

{
  "peerDependencies": {
    "react": "^17.0.0",
    "react-dom": "^17.0.0"
  }
}

进一步理解

peerDependencies 字段的主要作用是声明项目对某些依赖包的兼容性要求，但并不直接安装这些依赖包。它通常用于插件或库，以确保这些插件或库与宿主应用的依赖版本一致。

理解 peerDependencies 可以通过以下几个方面来更清晰：

声明依赖的兼容性：

当你的库或插件需要与某个主项目共享依赖时，peerDependencies 可以声明这些共享依赖的版本范围。例如，一个 React 组件库可能需要使用者项目中的 react 和 react-dom，但不希望自己安装这些依赖，因为它们应该由使用者项目来管理和安装。

避免版本冲突：

通过使用 peerDependencies，可以避免安装多个版本的同一个包，从而减少版本冲突的风险。如果每个库都各自安装自己的 react 版本，可能会导致不同版本的 react 互相冲突，从而引发错误。

假设你在开发一个 React 组件库：

package.json

json 复制代码

{
  "name": "my-react-library",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^17.0.0",
    "react-dom": "^17.0.0"
  }
}

使用者项目中安装你的库时，npm 会发出警告，提示需要安装特定版本的 react 和 react-dom：

bash 复制代码

npm install my-react-library

如果用户项目中没有安装 react 或 react-dom，或安装的版本与 peerDependencies 中指定的不兼容，npm 会显示警告信息。

例如，如果用户的项目中安装了 React 16 而不是 React 17，运行 npm install 时可能会看到这样的警告：

bash 复制代码

npm WARN [email protected] requires a peer of react@^17.0.0 but none is installed. You must install peer dependencies yourself.

用户需要确保其项目中的依赖版本与 peerDependencies 中声明的版本兼容。通常这意味着用户需要更新其项目中的相关依赖版本：

bash 复制代码

npm install react@^17.0.0 react-dom@^17.0.0

3.5 exports

exports 字段是在 Node.js 12 及其以上版本中引入的，用于指定模块的导出路径和条件导出。

它提供了一种更精细的方式来定义项目中的入口点和模块分发，支持不同的模块系统（如 CommonJS 和 ES Module）以及不同的运行环境（如浏览器和 Node.js）。

为什么使用 `exports`

更安全的模块导出：通过限制模块的导出路径，防止用户直接访问内部文件结构。
条件导出：根据运行环境或模块系统提供不同的导出文件。
简化入口点管理：统一管理多入口点。

`exports` 字段示例

假设你的项目结构如下：

复制代码

my-package/
├── package.json
├── index.js
├── index.mjs
└── lib/
    ├── feature.cjs
    ├── feature.mjs
    └── feature.js

你可以在 package.json 中使用 exports 字段来定义不同环境下的导出：

json 复制代码

{
  "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 文件。

使用场景

多模块系统支持：同时支持 CommonJS 和 ES Module。
环境特定导出：为浏览器和 Node.js 环境提供不同的导出文件。
模块拆分 ：可以根据需要将模块拆分成多个文件，并通过 exports 字段统一管理。

通过合理使用 exports 字段，可以使你的 Node.js 包在现代 JavaScript 生态系统中更具适应性和灵活性。

3.6 unpkg 和 jsdelivr

unpkg 和 jsDelivr 都是用于提供前端资源（如 JavaScript、CSS、图像等）的 CDN（内容分发网络）服务，使得开发者可以方便地在项目中引用这些资源而无需自行托管。

unpkg

json 复制代码

{
  "unpkg": "dist/umd/package.min.js"
}

这个字段告诉 unpkg CDN，当有人访问该包时，应该返回 dist/umd/package.min.js 文件。

unpkg 是一个快速、稳定的 CDN，用于托管 npm 中的开源包。它允许你通过简单地提供包名和版本号来直接引用 npm 包中的文件，而无需安装这些包或手动下载文件。通过 unpkg，你可以在浏览器中直接访问 npm 包中的任何文件。

例如，如果你想在项目中使用 React，你可以通过以下方式引用 React 的主要文件：

html 复制代码

<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

json 复制代码

{
  "jsdelivr": "dist/umd/package.min.js"
}

这个字段告诉 jsDelivr CDN，当有人访问该包时，应该返回 dist/umd/package.min.js 文件。

jsDelivr 是另一个流行的 CDN，提供了更多的功能和定制选项。它支持各种前端资源，包括 JavaScript 库、CSS 框架、图像、字体等。jsDelivr 的优点之一是它有多个节点，因此可以提供更快的下载速度和更高的可用性。

与 unpkg 类似，你可以使用 jsDelivr 来直接引用各种开源资源，而无需自行下载和托管。例如，你可以通过以下方式引用 jQuery：

html 复制代码

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>

共同特点

快速可靠：unpkg 和 jsDelivr 都是快速可靠的 CDN 服务，能够提供高性能的前端资源加载。
免费使用：它们都是免费使用的，任何人都可以直接引用它们提供的资源。
支持版本控制：你可以通过指定版本号来确保获取特定版本的资源，这有助于保持你的应用程序的稳定性和一致性。

如何选择

如果你只需要简单快速地引用 npm 包中的文件，并且不需要太多的定制选项，那么 unpkg 是一个不错的选择。
如果你需要更多的功能和定制选项，或者希望提供更好的性能和可用性，那么可以考虑使用 jsDelivr。

无论你选择哪个 CDN，它们都可以帮助你更轻松地管理前端资源，加速网站加载速度，并提高开发效率。

3.7 publishConfig

publishConfig 字段是 package.json 文件中的一个配置项，用于指定发布 npm 包时的额外设置。

通过 publishConfig 字段，你可以设置一些发布相关的配置，例如发布时的访问权限、发布时所使用的注册表等。

示例

以下是一个典型的 publishConfig 字段的示例：

json 复制代码

{
  "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 公共注册表。

使用场景

发布权限管理 : 如果你想发布一个私有的 npm 包，你可以将 access 设置为 "restricted"，只允许有权限的用户访问。
自定义注册表 : 如果你使用了自定义的 npm 注册表，你可以通过 registry 字段来指定发布时所使用的注册表的 URL。

注意事项

publishConfig 字段通常用于在发布 npm 包时自定义配置，但它并不是必需的。如果你没有特殊的需求，可以不用设置它。
如果你使用的是默认的 npm 公共注册表，并且不需要设置其他发布参数，那么通常不需要额外配置 publishConfig。

理解 publishConfig 字段的用途和配置选项，可以帮助你更好地管理和发布 npm 包。

3.8 sideEffects

sideEffects 是一个用于告知 webpack 和其他模块打包工具模块是否有副作用（side effects）的字段，出现在模块的 package.json 文件中。副作用是指模块执行时，不仅仅是导出一个值，而是会执行一些额外的操作，例如修改全局变量、执行某些代码等。

为什么需要 `sideEffects`

对于纯粹的 JavaScript 模块，大部分情况下，模块导入后只是为了获取导出的值，而不会对环境产生任何副作用。然而，一些模块可能会包含副作用，这些副作用可能会影响到整个应用程序的行为，甚至影响到其他模块。在模块打包时，如果可以确定某个模块没有副作用，打包工具就可以进行更多的优化，例如删除未使用的代码、提取公共代码等。而如果某个模块包含了副作用，打包工具则需要谨慎处理，以避免意外行为。

有关模块包含副作用的内容可以阅读 WHAT - Webpack 详解系列（七）。

Webpack 4 中新增了一个 sideEffects 特性，它允许我们通过配置标识我们的代码是否有副作用，从而提供更大的压缩空间。模块的副作用指的是：模块执行的时候除了导出成员，是否还做了其他的事情。这个特性一般只有我们去开发一个 npm 模块时才会用到。以自定义 npm 项目为例，那此时 Webpack 在打包某个模块之前，会先检查这个模块所属的 package.json 中的 sideEffects 标识，以此来判断这个模块是否有副作用，如果没有副作用的话，这些没用到的模块就不再被打包。

`sideEffects` 的取值

sideEffects 字段的取值可以是以下三种形式之一：

false: 表示模块没有副作用。这意味着打包工具可以安全地进行一些额外的优化。
true: 表示模块具有副作用。在打包时，打包工具将假定该模块具有副作用，并相应地处理它。
数组: 数组中的每个元素是一个匹配模式，表示具有副作用的文件路径。这些路径可以是文件名、文件夹名，也可以是通配符表达式。

示例

以下是一个 sideEffects 字段的示例：

json 复制代码

{
  "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 字段，可以帮助你更好地管理和优化你的模块打包过程。

3.9 browserslist

browserslist 是一个用于指定项目目标浏览器的字段，出现在项目根目录下的 package.json 文件中。它告知前端工具（例如 Autoprefixer、Babel、PostCSS 等）需要支持哪些浏览器版本，以便自动添加适当的 CSS 前缀或将 JavaScript 代码转换成兼容性更好的形式。

为什么需要 `browserslist`

Web 开发中，不同的浏览器对于一些 CSS 属性和 JavaScript 特性的支持程度有所差异。为了确保项目在不同浏览器中的兼容性，开发者通常需要根据项目需求选择目标浏览器，并进行相应的兼容性处理。

browserslist 的出现简化了这个过程，使得开发者只需在项目中设置一次目标浏览器列表，然后前端工具就可以根据这个列表自动进行相应的处理，大大提高了开发效率。

`browserslist` 的使用

你可以在 package.json 文件中的 browserslist 字段中指定目标浏览器的列表，也可以通过 .browserslistrc 文件或者 browserslist 配置文件来配置。

示例 browserslist 配置：

json 复制代码

"browserslist": [
  "last 2 versions",
  "> 1%",
  "IE 11"
],

这个配置表示项目的目标浏览器为：

最近两个版本的所有浏览器
浏览器市场份额大于 1% 的浏览器
Internet Explorer 11

json 复制代码

"browserslist": [
  "> 1%",
  "not ie 11",
  "not op_mini all"
],

这个配置表示项目的目标浏览器为：

浏览器市场份额大于 1% 的浏览器
不包括 Internet Explorer 11
不包括 Opera Mini 浏览器

使用场景

CSS 兼容性处理 : Autoprefixer 等工具可以根据 browserslist 配置自动添加 CSS 前缀，以确保样式在目标浏览器中的兼容性。
JavaScript 转换 : Babel 等工具可以根据 browserslist 配置自动将 ES6+ 的 JavaScript 代码转换成向下兼容的代码，以确保在目标浏览器中的兼容性。

注意事项

选择目标浏览器: 在选择目标浏览器时，应考虑项目的实际需求和用户群体使用的浏览器情况，避免过度或不必要的兼容性处理。
定期更新配置 : 随着浏览器的更新和市场份额的变化，建议定期更新 browserslist 配置，以确保项目始终针对最新的浏览器进行优化。

通过合理配置 browserslist，可以帮助开发者更轻松地管理项目的浏览器兼容性，提高开发效率。

WHAT - package.json 解释

目录

一、前言

二、介绍

2.1 package.json 文件示例

2.2 关键字段

2.3 常用命令

2.4 自定义脚本

三、element-plus 完整示例

3.1 main 和 module

1. main 字段

2. module 字段

3. 综合示例

3.2 types

1. 示例

2. TypeScript 类型定义文件的作用

3. 类型定义文件示例

4. 发布带有类型定义的包

3.3 styles

1. 示例

2. 用途

3.4 peerDependencies

1. dependencies

示例

2. devDependencies

示例

3. peerDependencies

示例

进一步理解

3.5 exports

为什么使用 exports

exports 字段示例

解释

更多复杂示例

使用场景

3.6 unpkg 和 jsdelivr

unpkg

jsDelivr

共同特点

如何选择

3.7 publishConfig

示例

使用场景

注意事项

3.8 sideEffects

为什么需要 sideEffects

sideEffects 的取值

示例

使用场景

注意事项

3.9 browserslist

为什么需要 browserslist

browserslist 的使用

使用场景

注意事项

2.1 `package.json` 文件示例

2. `module` 字段

为什么使用 `exports`

`exports` 字段示例

为什么需要 `sideEffects`

`sideEffects` 的取值

为什么需要 `browserslist`

`browserslist` 的使用