package.json文件配置说明

package.json文件配置

package.json文件是Node.js项目中的一个描述文件，执行npm init命令初始化项目后，在项目的根目录下自动生成该文件。

package.json包含了项目的配置信息以及项目所需的各种模块，使用npm install（简写：npm i）命令后会自动根据package.json下载所需的模块。

注： 在package.json中不能有注释否则会报错

1.package.json常见属性说明

name：名称{String}

version：版本{String}

private：
{ Boolean }
设置为 true，npm 就不会发布成功。
可以防止私有repositories不小心被发布出去。

description：项目描述，可用于 npm 官网搜索{String}

main：npm包项目的主要入口文件，必须的,{ String }
默认："./index.js"

browser:同 main，当包为 web 包时，browser 的优先级比 main 高

bin:定义了可执行文件{ String | Object }

man：项目手册（manuel）地址{ String | Array }

directories:用来描述各个功能模块存放的路径{ Object }

module：打包需要的入口文件

typings：TypeScript 的入口文件

files: 发布package时，控制哪些文件会发布上去{ Array | String }，如：
"files": ["src","dist/*.js","types/*.d.ts"]

gitHooks：代码质量检查，如：
"gitHooks": {"pre-commit": "lint-staged","commit-msg": "node scripts/verify-commit-msg.js"}

scripts：启动脚本，一般较长的命令可以设置脚本启动{ Object }

repository：git仓库所在位置{ Object | String }，如：
"repository": {"type": "git","url": "git地址"}

keywords：项目关键字，可用于 npm 官网搜索{String}

author：项目作者，只能存在一个作者{ String | Object }

contributors：贡献者{ Array }

maintainers：维护者{ Array }

license：开源协议{ String | Object }
除了设置合适的 license 类型外，还可以设置 "private": true 来避免项目发布。

bugs：bug地址{ String | Object }

homepage：项目官网地址{String}

dependencies:项目依赖（生产）{ Object }

devDependencies：项目依赖（开发）{ Object }

config：设置一些用于npm包的脚本命令会用到的配置参数{ Object }

peerDependencies：其他依赖包{ Object }

engines：指定项目所需要的node.js版本{ Object }，如：
"engines": {"node": ">=8.9.1","npm": ">=5.5.1","yarn": ">=1.3.2"}

browserslist：支持的浏览器，如：
"browserslist": ["last 3 Chrome versions","last 3 Firefox versions","Safari >= 10","Explorer >= 11","Edge >= 12","iOS >= 10","Android >= 6"]

2.属性详解

2.1 name

{ String }
项目名称。
如果想将项目发布到 npm 上去的话，该属性必需，且保证该 name 没有被占用。

命名规则：

• 长度小于等于 214 个字符
• 不能以点（.）或下划线（_）开头
• 新的包不能有大写字母
• 因为包名会被用作：URL 的一部分；命令行的参数；文件夹名。所以，包名不能包含非法字符

官方建议：

• 不要使用和 Node 核心模块一样的名称
• 包名中不要包含 js、node 等字眼。默认就是 js 文件，引擎也可以通过 engines 字段指定
• 包名起了是给别人用的，所以最好短点，且见名知意( 这个名字可能在require()方法中被调用 )
• 如果你想将项目发布到 npm 上的话，包名必需且唯一。所以起名之前最好先去官网查查有没有重名

tips: 此外，包还可以加前缀，将包放到同意的命名空间下（如 babel7）
如：@myorg/mypackage。

2.2 version

{ String }
项目版本号。
如果想将项目发布到 npm 上去的话，版本号必需，且和 name 组成唯一确定的包文件。

如果想升级项目并发布，只能更改版本号。
npm 的版本号是使用 node-semver 模块解析的。
格式采用 {major}.{feature}.{patch} （主版本 . 次要版本 . 补丁版本）模式：

• patch：修复 bug
• feature：新增功能
• major：重构 API

2.3bugs

{ String | Object }
提交项目 bug 的方式

{
  "url" : "提交 issue 的地址",
  "email" : "联系邮箱"
}

tips:这两个值都非必填，如果只提供 url 地址，可以写成如下格式：

"bugs" : "提交 issue 的地址"

如果提供了 url，npm bugs 命令会使用这个地址。

2.4 author

{ String | Object }
项目作者，只能存在一个作者

当属性为 Object 时

{
  "name" : "作者",
  "email" : "邮箱",
  "url" : "地址"
}

当属性为 String 时

"author" : "作者 <邮箱> (地址)"

2.5 files

{ Array | String }
默认："*"
当别人安装你的包时，所需要安装的文件

​ 遵循规则 :

• 命名规则和 .gitignore 一样，可以是个文件，也可以是文件夹，且支持 glob 规则（如 、**/ 等）

• 可以在根目录添加 .npmignore 文件来排除一些文件和文件夹

• 如果 .npmignore 缺省，将使用 .gitignore 来代替

• 不同通过 .npmignore 或 .gitignore 来排除 files 属性里面包含的文件

  不管如何配置，以下文件会始终会包含到包中 :

• package.json

• README

• CHANGES / CHANGELOG / HISTORY

• LICENSE / LICENCE

• NOTICE

• The file in the “main” field

README, CHANGES, LICENSE & NOTICE 支持任何后缀。

​ 不管如何配置，以下文件会始终不会包含到包中：

• .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)

2.6bin

{ String | Object }
定义了可执行文件

 { "bin" : { "myapp" : "./cli.js" } } 

局部安装，安装时会在 ./node_modules/.bin/ 下创建一个到 "./cli.js" 的软链。
全局安装，安装时会在 {prefix}/bin 下创建一个到 "./cli.js" 的软链。
执行 myapp 时实际上执行的是 "./cli.js"。

使用方式：

{
  "name": "my-program",
  "version": "1.2.5",
  "bin": "./path/to/program"
}
或
{
  "name": "my-program",
  "version": "1.2.5",
  "bin" : {
    "my-program" : "./path/to/program"
  }
}

注意：确保 bin 文件以 #!/usr/bin/env node 开头，否则脚本将不会在 node下运行

2.7directories

{ Object }
这个暂时属性没啥用。是用来描述各个功能模块存放的路径。算是预留接口吧。

{
  "directories" : {
    "lib" : "./lib",
    "bin" : "./bin",
    "man" : "./man",
    "doc" : "./doc",
    "example" : "./example",
    "test" : "./test"
  }
}

2.8repository

{ Object | String }
代码仓库地址

GitHub : 使用 npm docs 可以找到该项目

"repository": {
  "type" : "git",
  "url" : "git地址"
}

"repository": {
  "type" : "svn",
  "url" : "git地址"
}

GitHub, GitHub gist, Bitbucket, GitLab ：

"repository": "npm/npm"

"repository": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

除此之外，还可以使用 directory 指定代码路径

"repository": {
  "type" : "git",
  "url" : "https://github.com/facebook/react.git",
  "directory": "packages/react-dom"
}

2.9 scripts

“scripts”是一个由脚本命令组成的hash对象，他们在包不同的生命周期中被执行。

key是生命周期事件，value是要运行的命令。

自定义脚本命令，在命令行中通过执行npm run+变量来执行这段脚本

"scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint",
    "dev": "NODE_ENV=dev webpack-dev-server --progress --hot --host 0.0.0.0 --port 8089",
    "test": "NODE_ENV=test webpack --config webpack.test.config.js --progress", 
    "online": "NODE_ENV=production webpack --config webpack.online.config.js --progress",
    "node": "node server.js" 
}, 

在命令行输入：

​ npm run dev , 对应的命令就会被执行。

​ 这里有一个地方需要注意，当执行npm run xxx的时候，node_modules/.bin/目录会在运行时被加入系统的PATH变量。

​ 当我们在命令行输入：npm run build时，其实真正执行的命令是node_modules/.bin/webpack而不是webpack。

​ 当你的webpack并未全局安装时，直接在命令行输入：webpack是会报错的。

​ 因为你的webapck是安装在node_modules/.bin/下面的。

原理：

​ 使用npm run script执行脚本的时候都会创建一个shell，然后在shell中执行指定的脚本。

​ 这个shell会将当前项目的可执行依赖目录（node_modules/.bin）添加到环境变量path中，当执行之后之后再恢复原样。也就是说脚本命令中的依赖名会直接找到node_modules/.bin下面的对应脚本，而不需要加上路径。

使用：

npm run + 变量名称

注：现在为了方便常使用yarn来下载依赖与执行命令，所以运行项目时可以使用 yarn+变量名称

2.10 config

{ Object }
设置配置属性，配合 scripts 属性使用

{ "config" : { "port" : "8080" }

可以通过 process.env.npm_package_config_port 属性访问。也可以使用 npm config set foo:port 8001 命令改写。
webpack 的 process.env 的功能和他有点类似。
scripts 也可以直接传参，只不过是通过 npm_config_port 属性访问。

2.11 dependencies和devDependencies

执行npm i的时候会自动将两者引入的依赖下载到node_modules下。

这两者的区别就在于项目开发和运行时，如何安装所需要的依赖。我们的项目分为生产环境和开发环境，一般说的“项目上线”，就是打包开发环境下的代码发布到生产环境的这个过程。简单的说：

dependencies------生产环境

devdependencies------开发环境

在开发的时候，只需要考虑哪种依赖（模块）是开发的时候需要？还是上线的时候需要？或者两者都需要，比如引入Vue时，两者都需要，我们可以使用npm i vue -save-dev,再比如引入webpack，

该依赖只需开发环境下打包使用，线上不需要，所以我们可以使用npm i webpack -save-dev

常用的命令 ：

npm install module-name -save   自动把模块和版本号添加到dependencies部分
npm install module-name -save-dev   自动把模块和版本号添加到devdependencies部分

tips:
	'-save'可以简称为：-S
	'-save-dev'可以简称为：-D

2.12 peerDependencies

devDependencies和dependencies相似，如果你经常封装插件、使用一些ui组件库，自然对peerDependencies就不会陌生了。

• 问题的产生：

  在项目结构中，你引入了一个父类的包（A），当你需要引入类似父类下的一个子类包（B）时，是做不到的，因为node只会在项目的node_modules文件夹中找B，并不会先找到A，再从A文件夹找B。

• 问题的解决：

  引入peerDependencies配置：{ "peerDependencies": { "B": "1.0.0" } }就可以解决了

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies" : { "tea": "2.x" }
}