package.json各参数字段详解

[TokenYangForever]

前言

• package.json是每个npm包、基于node的项目中必不可少的配置文件，这里将详细介绍出现在package.json中的各个参数。参考自官方文档

  name

• npm包的名称，在你打算发布一个npm包时，name字段和version字段是必不可少的，并且必须是唯一的。而如果你并不是打算发布npm包的话，name和version字段都是可缺省的。name的命名规范如下：
  • 长度必须小于等于214个字符
  • 不能以"."或"_"开头
  • 不能用大写字母
  • 这个name字段最后会用作为URL的一部分、文件夹名称、以及命令行的参数。因此，不能包含对URL不安全的字符。

    version

• 和name一样，当你打算发布npm包时，version和name会作为包的唯一标识符。不打算发布npm包，则可以缺省。
• version必须经过node-semver解析，这是一个npm官方发布的一个关于version描述规范的npm包。

  description

• 一个string字段描述你的npm包，帮助其他人在npm search的时候发现你的npm包。

  keywords

• 一个字符串组成的数组字段，帮助其他人在npm search的时候发现你的npm包

  homepage

• 一个表示项目首页的url，一般是GitHub项目地址下的readme.md

  bugs

• 一个表示接收问题反馈的url地址，也可以是email地址。一般是Github项目下的issues。

  license

• 用于声明你的npm包使用的license，以便使用者知道该如何使用你的包，以及哪些限制的地方。

  author

• 包的作者的信息

  contributors

• 包的贡献者们的信息

  files

• 可缺省。用于描述当你的npm包被依赖时，一组用来描述包含的文件条目的文件模式(file pattern)，描述语法与.gitignore的相似。

  main

• main字段，用于描述你的npm包项目的主要入口文件。
• 比如你的包名称为foo，别人安装了你的包并用require('foo')引入包时，其实就是引入的main字段里描述的文件。
• 对于很多npm包来说，main字段是必须的，其他都无所谓了。

  browser

• 如果你的包打算是用在客户端的浏览器环境中，那么就应该用browser字段来代替main字段。这样来提示用户，包里面的代码可能会依赖一些node环境中不存在的内容(比如window对象)。

  bin

• 许多npm包中有一些想要安装到PATH里的可执行文件。在bin字段，可以定义一组由命令行命令与可执行文件目录为键值对组成的对象。
• 在你安装这个npm包时，全局安装的情况，bin字段就可以全局调用(会被安装到prefix/bin)，本地安装的话，则会把bin字段里定义的命令添加到当前项目的./node_modules/.bin/里。然后就可以在命令行直接执行这些命令，本质上就是执行对应的可执行文件。
• 举个例子：myapp包里面的package.json有这样的配置：{ "bin" : { "myapp" : "./cli.js" } }，那么在安装好myapp之后，就会生成一个cli.js文件与/usr/local/bin/myapp之间的映射关系。即执行myapp命令，就是在执行cli.js文件

  man

• 指定一个单个文件或者一个由数个文件组成的数组，这些事为man命令准备的。
• 比如你的包的package.json如下:

  { "name" : "foo"
  , "version" : "1.2.3"
  , "description" : "A packaged foo fooer for fooing foos"
  , "main" : "foo.js"
  , "man" : "./man/doc.1"
  }

• 那么在安装完npm包后，执行man foo就会去打开./man/doc.1文档显示。这些文件命名，都以数字命名，来表示分别安装到哪一个man section，如果文件是压缩后的，还要加上.gz后缀。

  repository

• 指明你的项目源代码仓库所在位置，这有助于其他人为你的项目贡献(contribute)代码，如果你的git项目是托管在GitHub上的，那么npm docs命令是能够找到的。
• 像下面这样设置：

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

• 如果使用的svn则像这样：

  "repository" :
  { "type" : "svn"
  , "url" : "https://v8.googlecode.com/svn/trunk/"
  }

• url字段应该为一个公共的可访问的URL地址，这个URL地址可以直接交给版本控制系统(VCS)处理，这不应该是一个你的项目页面的html地址，它不是提供给浏览器的，而是提供给计算机的。
• type则是表明，VCS的类型，一般都是用的git。

  scripts

• script字段是一个包含脚本命令的词典(dictionary)，key值为生命周期的事件(lifecycle event)/或者自定义的命令，value值为具体的需要执行的命令。
• 参考npm-scripts，查看具体的生命周期以及关于scripts属性详细的说明。
• 下面举个简单的示例：

  { "scripts" :
  { "install" : "scripts/install.js", 
  "postinstall" : "scripts/install.js",
  "uninstall" : "scripts/uninstall.js",
  "build": "node scripts/build.js"
  }
  }

• 上面前三个是npm安装的生命周期事件，比如install就表示，在安装npm包时执行后面的命令。而最后一个build就是自定义的命令了，可以用npm run build来执行，相当于是执行node scripts/build.js

  config

• config对象用来设置一些用于npm包的脚本命令会用到的配置参数。查看npm-config了解更多。

  dependencies

• dependencies属性是一个简单的对象，包含了npm包名字与版本范围(version range)的映射。版本范围是一个字符串，包含了一个或多个描述符。dependencies同样可以用一个tarball或git url来定义。
• 测试用的包或编译代码的包不应该放在dependencies对象，而应该放在devDependencies里。
• 下面是一些版本范围的描述符
  • version 版本号必须严格匹配等于version
  • >version 版本号必须比version大
  • >=version 大于等于
  • <version 小于
  • <=version 小于等于
  • ~version "近似等价于version" 参考semver
  • ^version "与version相兼容" 参考semver
  • 1.2.x 1.2开头的版本号都可以，1.2.0、1.2.1等等，但不能是1.1或1.3其他的。
  • • 匹配任意版本号
  • "" 空字符串与 * 相同
  • version1 - version2 相当于 >=version1 <=version2.
  • range1 || range2 range1和range2其中一个版本号.

    devDependencies

• devDependencies结构和dependencies相似，但是都是开发时所依赖的包，如果别人只是使用或下载你的npm包，就不需要安装这里面的

  engine

• engine字段用来表示，你的项目所运行的node版本。不指定engine字段，或者用*表示不限制node版本。

  os

• os字段表示你的npm包要在哪个操作系统上面运行

  cpu

• 如果你的包需要运行在某些特定的CPU架构，则用cpu字段来描述。