npm - package.json 配置项详解

濮阳和泰

2023-12-01

前言

它是一个位于 Node.js 项目根目录中的配置文件，管理整个项目的依赖项和元数据。

例如，您拿到项目后，一定使用过如下命令安装过项目依赖：

npm install

像 npm / yarn 这类包管理工具，通过 package.json 文件识别项目并了解如何处理项目的依赖关系。

官方文档

https://docs.npmjs.com/cli/v8/configuring-npm/package-json

name（必填）

项目名称，全部小写字母，不能超过 214 个字符，允许使用下划线和中横线，但不允许使用空格或其它字符。

version（必填）

版本号，格式 x.y.z，符合 NPM 语义版本控制要求。

x：主版本号，新增功能，不兼容之前版本。
y：次版本号，新增功能，但兼容之前版本。
z：PATCH 补丁版本号，修复 BUG，且兼容之前版本

description

项目描述，用于描述项目及 npm 收录检索，用户搜索时会列为关键字。

license

软件许可证，值通常是许可证的标识符代码，如 BSD / MIT 等。

author

项目作者，一个人。

"author": "李拴蛋"

也可以是一个 JSON 对象：

"author": {
    "name": "李拴蛋",
    "email": "wangjiabinweb@163.com",
    "url": "https://www.baidu.com"
}

contributors

项目作者，一组人（组织），数组类型，数组中每项和 author 格式一致。

"contributors": [
	{
		"name": "李拴蛋",
	    "email": "wangjiabinweb@163.com",
	    "url": "https://www.baidu.com"
	},
	...
]

private

如果这个属性被设置为 true，npm 将拒绝发布它，这是为了防止一个私有模块被无意间发布出去。

如果只想让模块被发布到一个特定的 npm 仓库，如一个内部的仓库，可与在下面的 publishConfig 中配置仓库参数。

publishConfig

这个配置是会在模块发布时用到的一些值的集合。如果不想模块被默认被标记为最新的，或者默认发布到公共仓库，可以在这里配置 tag 或仓库地址。

keywords

字符串数组，用于 npm 搜索关键字。

main

指定加载的入口文件，使用 require('moduleName') 时便会加载此文件，默认值为模块根目录下的 index.js。

browser 浏览器环境和 node 环境均可使用。

browser

定义了 npm 包在 browser 浏览器环境下的入口文件。

scripts

指定运行脚本命令的 npm 命令行缩写，比如 serve 指定了运行 npm run serve 时真正执行的命令。

以下设置指定了运行 npm run serve / npm run lint / npm run mock 时要执行的命令。

"scripts": {
    "serve": "concurrently \"npm:mock\" \"vue-cli-service serve\"",
    "lint": "vue-cli-service lint",
    "mock": "cd mock && ts-node-dev mock-server.ts"
}

config

用于添加命令行环境变量，JSON 对象，值在 Scripts 的整个周期中皆可用，专门用于给 Scripts 提供配置参数。

bin

指定各内部命令对应的可执行文件的位置。如以下配置指定 someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。

"bin": {
    "someTool": "./bin/someTool.js"
}

npm 会查找这个文件，在 node_modules/.bin/ 目录下建立符号链接 node_modules/.bin/someTool。

由于 node_modules/.bin/ 目录在运行时加入系统的 PATH 变量，因此运行 npm 时可以不带路径，直接通过命令运行这些脚本。

所有 node_modules/.bin/ 目录下的命令都可以使用 npm run [命令] 执行，在命令行下键入 npm run 后按 Tab 键就会显示所有可使用的命令。

engines

指定运行的平台，如 Node.js 的某个版本、NPM 版本或浏览器。

repository

代码存放位置，例如在 Github 上。

"repository": {
    "type": "git",
    "url": "https://github.com/..."
}

dependencies（重要）

指定项目运行需要依赖的模块，JSON 对象类型，每个对象成员分别由模块名和对应版本要求组成，表示依赖的模块和其版本范围。

"dependencies": {
    "echarts": "4.2.1",
    "axios": "^0.19.0",
    "js-cookie": "~2.2.0",
    "sortablejs": "latest"
}

版本号限定分以下几种：

指定版本号：如上例中的 echarts，只安装指定版本。
^ + 指定版本号：如上例中的 axios，表示安装同一主版本号下的最新版本，即只能安装 0.x.x 版本，不能安装 1.x.x 版本。
~ + 指定版本号：如上例中的 js-cookie，表示安装同一主版本号和次版本号下的最新版本，即只能安装 2.2.x 版本，不能安装 2.3.x 版本。
latest：直接安装最新版本（慎重）。

devDependencies（重要）

指定项目开发需要依赖的模块，同 dependencies 一样也是一个 JSON 对象类型，每个对象成员分别由模块名和对应版本要求组成，表示依赖的模块和其版本范围。

版本号限定规则和 dependencies（上方） 一致。

bugs

问题跟踪系统地址或邮箱，npm bugs 时使用，例如：

"bugs": "https://github.com/..."

gitHooks

@vue/cli-service 安装后会安装 yorkie，允许在 package.json 的 gitHooks 字段中方便地指定 Git Hook。

homepage

项目 url 主页，例如：

"homepage": "https://github.com/xxx/project"

files

它是一个文件数组，描述了将软件包作为依赖项安装时要包括的条目。如果在数组里面声明了一个文件夹，那也会包含文件夹中的文件。某些特殊文件和目录也被包括或排除在外，无论它们是否存在于文件数组中。

以下文件无论是否设置，总是包含：
*   `package.json`
*   `README`
*   `CHANGES`/`CHANGELOG`/`HISTORY`
*   `LICENSE`/`LICENCE`
*   `NOTICE`
*   The file in the “main” field

以下文件总是被忽略：
*   `.git`
*   `CVS`
*   `.svn`
*   `.hg`
*   `.lock-wscript`
*   `.wafpickle-N`
*   `.*.swp`
*   `.DS_Store`
*   `._*`
*   `npm-debug.log`
*   `.npmrc`
*   `node_modules`
*   `config.gypi`
*   `*.orig`
*   `package-lock.json`(use shrinkwrap instead)

peerDependencies

有时，你的项目和所依赖的模块，都会同时依赖另一个模块，但是所依赖的版本不一样。

比如，你的项目依赖 A 模块和 B 模块的 1.0 版，而 A 模块本身又依赖B模块的 2.0 版。

大多数情况下，这不构成问题，B 模块的两个版本可以并存，同时运行。但是，有一种情况，会出现问题，就是这种依赖关系将暴露给用户。

最典型的场景就是插件，比如 A 模块是 B 模块的插件。用户安装的 B 模块是 1.0 版本，但是 A 插件只能和 2.0 版本的 B 模块一起使用。

这时，用户要是将 1.0 版本的 B 的实例传给 A，就会出现问题。因此，需要一种机制，在模板安装的时候提醒用户，如果 A 和 B 一起安装，那么 B 必须是 2.0 模块。

peerDependencies 字段，就是用来供插件指定其所需要的主工具的版本。

{
  "name": "chai-as-promised",
  "peerDependencies": {
    "chai": "1.x"
  }
}

上面代码指定，安装 chai-as-promised 模块时，主程序 chai 必须一起安装，而且 chai 的版本必须是 1.x。如果你的项目指定的依赖是 chai 的 2.0 版本，就会报错。

注意，从 npm 3.0 版开始，peerDependencies 不再会默认安装了。

os

指定你的项目将运行在什么操作系统上。

cpu

指定你的项目将运行在什么cpu架构上。