1. 概述
如果使用 JavaScript、或者曾经与 JavaScript 项目、Node.js 或前端项目进行过交互，则肯定会遇到过 package.json 文件。
它有什么用途？应该了解它的什么，可以使用它完成哪些有趣的事情？
package.json 文件是项目的清单。 它可以做很多完全互不相关的事情。 例如，它是用于工具的配置中心。 它也是 npm 和 yarn 存储所有已安装软件包的名称和版本的地方。
对于应用程序，package.json 文件中的内容没有固定的要求。 唯一的要求是必须遵守 JSON 格式，否则，尝试以编程的方式访问其属性的程序则无法读取它。
如果要构建要在 npm 上分发的 Node.js 软件包，则必须具有一组可帮助其他人使用它的属性。
2.解析说明
{
"name": "example-project",
"version": "1.0.0",
"description": "package.json解析",
"main": "src/main.js",
"private": true,
"scripts": {
"dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
"start": "npm run dev",
"unit": "jest --config test/unit/jest.conf.js --coverage",
"test": "npm run unit",
"lint": "eslint --ext .js,.vue src test/unit",
"build": "node build/build.js"
},
"dependencies": {
"vue": "^2.5.2"
},
"devDependencies": {
"autoprefixer": "^7.1.2",
"babel-core": "^6.22.1",
"babel-eslint": "^8.2.1",
"babel-helper-vue-jsx-merge-props": "^2.0.3",
"babel-jest": "^21.0.2",
"babel-loader": "^7.1.1",
"babel-plugin-dynamic-import-node": "^1.2.0",
"babel-plugin-syntax-jsx": "^6.18.0",
"babel-plugin-transform-es2015-modules-commonjs": "^6.26.0",
"babel-plugin-transform-runtime": "^6.22.0",
"babel-plugin-transform-vue-jsx": "^3.5.0",
"babel-preset-env": "^1.3.2",
"babel-preset-stage-2": "^6.22.0",
"chalk": "^2.0.1",
"copy-webpack-plugin": "^4.0.1",
"css-loader": "^0.28.0",
"eslint": "^4.15.0",
"eslint-config-airbnb-base": "^11.3.0",
"eslint-friendly-formatter": "^3.0.0",
"eslint-import-resolver-webpack": "^0.8.3",
"eslint-loader": "^1.7.1",
"eslint-plugin-import": "^2.7.0",
"eslint-plugin-vue": "^4.0.0",
"extract-text-webpack-plugin": "^3.0.0",
"file-loader": "^1.1.4",
"friendly-errors-webpack-plugin": "^1.6.1",
"html-webpack-plugin": "^2.30.1",
"jest": "^22.0.4",
"jest-serializer-vue": "^0.3.0",
"node-notifier": "^5.1.2",
"optimize-css-assets-webpack-plugin": "^3.2.0",
"ora": "^1.2.0",
"portfinder": "^1.0.13",
"postcss-import": "^11.0.0",
"postcss-loader": "^2.0.8",
"postcss-url": "^7.2.1",
"rimraf": "^2.6.0",
"semver": "^5.3.0",
"shelljs": "^0.7.6",
"uglifyjs-webpack-plugin": "^1.1.1",
"url-loader": "^0.5.8",
"vue-jest": "^1.0.2",
"vue-loader": "^13.3.0",
"vue-style-loader": "^3.0.1",
"vue-template-compiler": "^2.5.2",
"webpack": "^3.6.0",
"webpack-bundle-analyzer": "^2.9.0",
"webpack-dev-server": "^2.9.1",
"webpack-merge": "^4.1.0"
},
"engines": {
"node": ">= 6.0.0",
"npm": ">= 3.0.0"
},
"browserslist": ["> 1%", "last 2 versions", "not ie <= 8"]
}
这里有很多东西：
- name 设置了应用程序/软件包的名称。
- version 表明了当前的版本。
- description 是应用程序/软件包的简短描述。
- main 设置了应用程序的入口点。
- private 如果设置为 true，则可以防止应用程序/软件包被意外地发布到 npm。
- scripts 定义了一组可以运行的 node 脚本。
- dependencies 设置了作为依赖安装的 npm 软件包的列表。
- devDependencies 设置了作为开发依赖安装的 npm 软件包的列表。
- engines 设置了此软件包/应用程序在哪个版本的 Node.js 上运行。
- browserslist 用于告知要支持哪些浏览器（及其版本）。
以上所有的这些属性都可被 npm 或其他工具使用
1. name字段
package.json文件中最重要的就是name和version字段，这两项是必填的。名称和版本一起构成一个标识符，该标识符被认为是完全唯一的。对包的更改应该与对版本的更改一起进行。
name必须小于等于214个字符，不能以.或_开头，不能有大写字母，因为名称最终成为URL的一部分因此不能包含任何非URL安全字符。
npm官方建议我们不要使用与核心节点模块相同的名称。不要在名称中加js或node。如果需要可以使用engines来指定运行环境。
该名称会作为参数传递给require，因此它应该是简短的，但也需要具有合理的描述性
2.version字段
version一般的格式是x.x.x, 并且需要遵循该规则。
package.json文件中最重要的就是name和version字段，这两项是必填的。名称和版本一起构成一个标识符，该标识符被认为是完全唯一的。每次发布时version不能与已存在的一致。
- description字段
description是一个字符串，用于编写描述信息。有助于人们在npm库中搜索的时候发现你的模块。 - keywords字段
keywords是一个字符串组成的数组，有助于人们在npm库中搜索的时候发现你的模块。 - homepage字段
homepage项目的主页地址。 - bugs字段
bugs用于项目问题的反馈issue地址或者一个邮箱。
"bugs": {
"url" : "https://github.com/owner/project/issues",
"email" : "[email protected]"
}
复制代码 - license字段
license是当前项目的协议，让用户知道他们有何权限来使用你的模块，以及使用该模块有哪些限制。
"license" : "BSD-3-Clause"
复制代码 - author字段 contributors字段
author是具体一个人，contributors表示一群人，他们都表示当前项目的共享者。同时每个人都是一个对象。具有name字段和可选的url及email字段。
"author": {
"name" : "yindong",
"email" : "[email protected]",
"url" : "https://zhiqianduan.com/"
}
复制代码
也可以写成一个字符串
"author": "yindong [email protected] (https://zhiqianduan.com/)"
复制代码 - files字段
files属性的值是一个数组，内容是模块下文件名或者文件夹名，如果是文件夹名，则文件夹下所有的文件也会被包含进来（除非文件被另一些配置排除了）
可以在模块根目录下创建一个.npmignore文件，写在这个文件里边的文件即便被写在files属性里边也会被排除在外，这个文件的写法与.gitignore类似。 - main字段
main字段指定了加载的入口文件，require导入的时候就会加载这个文件。这个字段的默认值是模块根目录下面的index.js。 - bin字段
bin项用来指定每个内部命令对应的可执行文件的位置。如果你编写的是一个node工具的时候一定会用到bin字段。
当我们编写一个cli工具的时候，需要指定工具的运行命令，比如常用的webpack模块，他的运行命令就是webpack。
"bin": {
"webpack": "bin/index.js",
}
复制代码
当我们执行webpack命令的时候就会执行bin/index.js文件中的代码。
在模块以依赖的方式被安装，如果存在bin选项。在node_modules/.bin/生成对应的文件，
Npm会寻找这个文件，在node_modules/.bin/目录下建立符号链接。由于node_modules/.bin/目录会在运行时加入系统的PATH变量，因此在运行npm时，就可以不带路径，直接通过命令来调用这些脚本。
所有node_modules/.bin/目录下的命令，都可以用npm run [命令]的格式运行。在命令行下，键入npm run，然后按tab键，就会显示所有可以使用的命令。 - man字段
man用来指定当前模块的man文档的位置。
"man" :[ "./doc/calc.1" ]
复制代码 - directories字段
directories制定一些方法来描述模块的结构, 用于告诉用户每个目录在什么位置。 - repository字段
指定一个代码存放地址，对想要为你的项目贡献代码的人有帮助
"repository" : {
"type" : "git",
"url" : "https://github.com/npm/npm.git"
}
复制代码 - scripts字段
scripts指定了运行脚本命令的npm命令行缩写，比如start指定了运行npm run start时，所要执行的命令。
"scripts": {
"start": "node ./start.js"
}
复制代码
使用scripts字段可以快速的执行shell命令，可以理解为alias。
scripts可以直接使用node_modules中安装的模块，这区别于直接运行需要使用npx命令。
"scripts": {
"build": "webpack"
}
// npm run build
// npx webpack
复制代码
- config字段
config字段用于添加命令行的环境变量。
{
"name" : "yindong",
"config" : { "port" : "8080" },
"scripts" : { "start" : "node server.js" }
}
复制代码
然后，在server.js脚本就可以引用config字段的值。
console.log(process.env.npm_package_config_port); // 8080
复制代码
用户可以通过npm config set来修改这个值。
npm config set yindong:port 8000
复制代码 - dependencies字段, devDependencies字段
dependencies字段指定了项目运行所依赖的模块，devDependencies指定项目开发所需要的模块。
它们的值都是一个对象。该对象的各个成员，分别由模块名和对应的版本要求组成，表示依赖的模块及其版本范围。
当安装依赖的时候使用--save参数表示将该模块写入dependencies属性，--save-dev表示将该模块写入devDependencies属性。
"devDependencies": {
"webpack": "^5.38.1",
}
复制代码
对象的每一项通过一个键值对表示，前面是模块名称，后面是对应模块的版本号。版本号遵循“大版本.次要版本.小版本”的格式规定。
版本说明
固定版本: 比如5.38.1，安装时只安装指定版本。
波浪号: 比如~5.38.1, 表示安装5.38.x的最新版本（不低于5.38.1），但是不安装5.39.x，也就是说安装时不改变大版本号和次要版本号。
插入号: 比如ˆ5.38.1, ，表示安装5.x.x的最新版本（不低于5.38.1），但是不安装6.x.x，也就是说安装时不改变大版本号。需要注意的是，如果大版本号为0，则插入号的行为与波浪号相同，这是因为此时处于开发阶段，即使是次要版本号变动，也可能带来程序的不兼容。
latest: 安装最新版本。
- 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字段，就是用来供插件指定其所需要的主工具的版本。可以通过peerDependencies字段来限制，使用myless模块必须依赖less模块的3.9.x版本.
{
"name": "myless",
"peerDependencies": {
"less": "3.9.x"
}
}
复制代码
注意，从npm 3.0版开始，peerDependencies不再会默认安装了。就是初始化的时候不会默认带出。 - bundledDependencies字段
bundledDependencies指定发布的时候会被一起打包的模块. - optionalDependencies字段
如果一个依赖模块可以被使用， 同时你也希望在该模块找不到或无法获取时npm继续运行，你可以把这个模块依赖放到optionalDependencies配置中。这个配置的写法和dependencies的写法一样，不同的是这里边写的模块安装失败不会导致npm install失败。 - engines字段
engines字段指明了该模块运行的平台，比如Node或者npm的某个版本或者浏览器。
{ "engines" : { "node" : ">=0.10.3 <0.12", "npm" : "~1.0.20" } }
复制代码 - os字段
可以指定你的模块只能在哪个操作系统上运行
"os" : [ "darwin", "linux", "win32" ]
复制代码 - cpu字段
限制模块只能在某种架构的cpu下运行
"cpu" : [ "x64", "ia32" ]
复制代码 - private字段
如果这个属性被设置为true，npm将拒绝发布它，这是为了防止一个私有模块被无意间发布出去。
"private": true
复制代码 - publishConfig字段
这个配置是会在模块发布时生效，用于设置发布用到的一些值的集合。如果你不想模块被默认标记为最新的，或者默认发布到公共仓库，可以在这里配置tag或仓库地址。
通常publishConfig会配合private来使用，如果你只想让模块被发布到一个特定的npm仓库，如一个内部的仓库。
"private": true,
"publishConfig": {
"tag": "1.0.0",
"registry": "https://registry.npmjs.org/",
"access": "public"
}
复制代码 - preferGlobal字段
preferGlobal的值是布尔值，表示当用户不将该模块安装为全局模块时（即不用–global参数），要不要显示警告，表示该模块的本意就是安装为全局模块。
"preferGlobal": false
复制代码 - browser字段
browser指定该模板供浏览器使用的版本。Browserify这样的浏览器打包工具，通过它就知道该打包那个文件。
"browser": {
"tipso": "./node_modules/tipso/src/tipso.js"
},
参考文档
- http://caibaojian.com/npm/files/package.json.html
- http://nodejs.cn/learn/the-package-json-guide#%E8%BD%AF%E4%BB%B6%E5%8C%85%E7%89%88%E6%9C%AC
- http://javascript.ruanyifeng.com/nodejs/packagejson.html