package.json详解

* 注意package.json必须是纯JSON的，而不仅仅是一个JavaScript对象字面量。

   该文件描述的很多行为都受npm-config中的配置影响。

下面分别介绍package.json中各个字段的含义和用法。

name

name和version字段是package.json文件中最重要的字段。这是必须的字段，如果你的npm包没有指定这两个字段，将无法被安装。name和version字段被假定组合成一个唯一的标识符。包内容的更改和包版本的更改是同步的。

name字段的含义不需要过多解释，就是npm包名。

几个规则：

1. name的长度必须小于等于214个字符。
2. name不能以"."(点)或者"_"(下划线)开头。
3. name中不能包含大写字母。
4. name最终将被用作URL的一部分、命令行的参数和文件夹名。因此，name不能含有非URL安全的字符。

几个建议：

1. 不要使用已存在的name作为包名。
2. 不要在name中使用"js"和"node"，这会假定这是js文件，一旦你写一个package.json文件，你就可以在"engines"字段中指定解释器引擎。
3. name字段可能会被作为传输传递给require()函数，因此它最好是简短的、自描述的。
4. 你可能会需要在深入开发一个包之前先检查npm的registry来确认某个name是否被使用过，可以参考https://www.npmjs.com/。

一个name可以用scope来指定一个前缀，比如@myorg/mypackage，可以参考npm-scope。

version

name和version字段是package.json文件中最重要的字段。这是必须的字段，如果你的npm包没有指定这两个字段，将无法被安装。name和version字段被假定组合成一个唯一的标识符。包内容的更改和包版本的更改是同步的。

version字段必须能够被node-semver解析，node-semver作为依赖项被捆绑进了npm中。(可以使用npm install semver来使用)

关于版本号和范围的信息可以参考semver。

description

npm包的描述，description是一个字符串。它可以帮助人们在使用npm search时找到这个包。

keywords

npm包的关键字，keywords是一个字符串的数组。它可以帮助人们在使用npm search时找到这个包。

homepage

项目主页的url。

注意：这和"url"不一样。如果你放一个"url"字段，registry会以为是一个跳转到你发布在其他地方的地址，然后鄙视你。

bugs

改项目的issue跟踪页面或这报告issue的email地址。这对使用这个包遇到问题的用户会有帮助。

差不多是这样：

{ 　　"url" : "https://github.com/owner/project/issues",　　"email" : "[e-mail]"}

你可以择其一或者两个都写上。如果只想提供一个url，你可以对"bugs"字段指定一个字符串而不是object。

如果提供了一个url，它会被用于npm bugs命令。

license

你应该对你的包指定一个license来让用户知道他们的使用权利和和任何限制。

如果你正在使用BSD-2-Clause或MIT这样的通用许可证，可以为你的license添加一个当前SPDX的许可证标识符，比如：

{ "license" : "BSD-3-Clause" }

你可以查看SPDX许可证标识符的完整列表，理想情况下你应该挑选一个经过OSI核准的标识符。

如果你的包在多个通用许可证下被授权，使用一个SPDX许可证表达式语法v2.0，比如：

{ "license" : "(ISC OR GPL-3.0)" }

如果你正在使用的许可未被授予一个SPDX标识符，或者你正在使用自定义的许可证，使用如下：

{ "license" : "SEE LICENSE IN <filename>" }

然后在包的根目录下提供一个叫<filename>的许可证文件。

一些旧的包使用license对象或一个"license"属性包含一个license的数组：

// Not valid metadata{ "license" :    {         "type" : "ISC"，        "url" : "http://opensource.org/licenses/ISC"    }}        

//Notvalidmetadata{    "licenses": [        {            "type": "MIT",            "url": "http://www.opensource.org/licenses/mit-license.php"        },        {            "type": "Apache-2.0",            "url": "http://opensource.org/licenses/apache2.0.php"        }    ]}

上述这种风格的写法已经被废弃了，取而代之的是SPDX表达式：

{ "license": "ISC" }{ "license": "(MIT OR Apache-2.0)" }

最后，如果你不希望授权别人以任何形式使用私有包或未发布的包，可以这样写：

{ "license": "UNLICENSED"}

也可以设置：

"private": true

来防止意外的发布。

关于人的字段: author, contributors

author是一个人，contributors是一些人的数组。person是一个对象，拥有必须的name字段和可选的url和email字段，像这样：

{    "name": "Barney Rubble",    "email": "[e-mail]",    "url": "http://barnyrubble.tumblr.com/"}

或者你也可以使用单个字符串的精简形式，npm会帮你解析它：

"Barney Rubble <[e-mail]> (http://barnyrubble.tumblr.com/)"

这里email和url也是可选的。

npm也会使用你提供的npm用户信息来设置一个顶级的"maintainers"字段。

files

files字段是一个被项目包含的文件名数组，如果你在里面放一个文件夹名，那么这个文件夹中的所有文件都会被包含进项目中(除非是那些在其他规则中被忽略的文件)。

你还可以在包的根目录或子目录下提供一个".npmignore"文件来忽略项目包含文件，即使这些文件被包含在files字段中。.npmignore文件和.gitignore的功能很像。

某些文件总是被包含的，不论是否在规则中指定了它们：

package.json
README (and its variants)
CHANGELOG (and its variants)
LICENSE / LICENCE

相反地，一些文件总是被忽略：

.git
CVS
.svn
.hg
.lock-wscript
.wafpickle-N
*.swp
.DS_Store
._*
npm-debug.log

main

main字段指定了模块的入口程序文件。就是说，如果你的模块名叫"foo"，用户安装了它，并且调用了 require("foo")，则这个main字段指定的模块的导出对象会被返回。

这应该是一个相对于包根目录的模块标识。

对于大部分模块来说，main字段除了指定一个主入口文件以外没什么其他用处了。