关于npm:你不知道的packagejson属性

概述

package.json必须是一个严格的json文件，而不仅仅是js里边的一个对象。其中很多属性能够通过npm-config来生成

name

package.json中最重要的属性是name和version两个属性，这两个属性是必须要有的，否则模块就无奈被装置，这两个属性一起造成了一个npm模块的惟一标识符。模块中内容变更的同时，模块版本也应该一起变动。
name属性就是你的模块名称，上面是一些命名规定:

name必须小于等于214个字节，包含前缀名称在内（如 xxx/xxxmodule）。
name不能以"_"或"."结尾
不能含有大写字母
name会成为url的一部分，不能含有url非法字符
上面是官网文档的一些倡议：
不要应用和node外围模块一样的名称
name中不要含有"js"和"node"。 It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)
name属性会成为模块url、命令行中的一个参数或者一个文件夹名称，任何非url平安的字符在name中都不能应用，也不能以"_"或"."结尾
name属性兴许会被写在require()的参数中，所以最好取个简短而语义化的值。
创立一个模块前能够先到后边的网址查查name是否曾经被占用. https://www.npmjs.com/
- ```
# 公布一个包的时候，须要测验某个包名是否存在npm search <ModuleName>
```
  name属性能够有一些前缀如 e.g. @myorg/mypackage.在npm-scope(7)的文档中能够看到具体阐明
  version
  version必须能够被npm依赖的一个node-semver模块解析。具体规定见上面的dependencies模块
  description
  一个形容，不便他人理解你的模块作用，搜寻的时候也有用。
  keywords
  一个字符串数组，不便他人搜寻到本模块
  homepage
  我的项目主页url
  留神: 这个我的项目主页url和url属性不同，如果你填写了url属性，npm注册工具会认为你把我的项目公布到其余中央了，获取模块的时候不会从npm官网仓库获取，而是会重定向到url属性配置的地址。
  （原文档中用了 spit(吐)这个单词，作者示意他不是在开玩笑:）
  bugs
  填写一个bug提交地址或者一个邮箱，被你的模块坑到的人能够通过这里吐槽，例如：
```
{"url" : "https://github.com/owner/project/issues","email" : "project@hostname.com"}
```
  url和email能够任意填或不填，如果只填一个，能够间接写成一个字符串而不是对象。如果填写了url，npm bugs命令会应用这个url。
  license
  你应该为你的模块制订一个协定，让用户晓得他们有何权限来应用你的模块，以及应用该模块有哪些限度。最简略的，例如你用BSD-3-Clause 或 MIT之类的协定，如下：
```
{ "license" : "MIT" }
```
  你能够在https://spdx.org/licenses/ 这个地址查阅协定列表。
  和用户相干的属性: author, contributors
  author是一个码农， contributors是一个码农数组。 person是一个有一些形容属性的对象，如下 like this:
```
{"name" : "Barney Rubble","email" : "b@rubble.com","url" : "http://barnyrubble.tumblr.com/"}
```
  也能够按如下格局缩写，npm会帮着转换:
```
"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)"
```
  email和url属性实际上都是能够省略的。形容用户信息的还有一个maintainers（维护者）属性。
  files
  files属性的值是一个数组，内容是模块下文件名或者文件夹名，如果是文件夹名，则文件夹下所有的文件也会被蕴含进来（除非文件被另一些配置排除了）
  你也能够在模块根目录下创立一个.npmignore文件（windows下无奈间接创立以"."结尾的文件，应用linux命令行工具创立如git bash），写在这个文件里边的文件即使被写在files属性里边也会被排除在外，这个文件的写法".gitignore"相似。
  main
  main属性指定了程序的主入口文件。意思是，如果你的模块被命名为foo，用户装置了这个模块并通过require("foo")来应用这个模块，那么require返回的内容就是main属性指定的文件中 module.exports指向的对象。
  它应该指向模块根目录下的一个文件。对大对数模块而言，这个属性更多的是让模块有一个主入口文件，然而很多模块并不写这个属性。
  bin
  很多模块有一个或多个须要配置到PATH门路下的可执行模块，npm让这个工作变得非常简略（实际上npm自身也是通过bin属性装置为一个可执行命令的）
  如果要用npm的这个性能，在package.json里边配置一个bin属性。bin属性是一个已命令名称为key，本地文件名称为value的map如下：
```
{"bin" : { "myapp" : "./cli.js" }}
```
  模块装置的时候，若是全局装置，则npm会为bin中配置的文件在bin目录下创立一个软连贯（对于windows零碎，默认会在C:\Users\username\AppData\Roaming\npm目录下），若是部分装置，则会在我的项目内的./node_modules/.bin/目录下创立一个软链接。
  因而，按下面的例子，当你装置myapp的时候，npm就会为cli.js在/usr/local/bin/myapp门路创立一个软链接。
  如果你的模块只有一个可执行文件，并且它的命令名称和模块名称一样，你能够只写一个字符串来代替下面那种配置，例如：
```
{ "name": "my-program","version": "1.2.5", "bin": "./path/to/program"}
```
  作用和如下写法雷同:
```
{ "name": "my-program", "version": "1.2.5", "bin" : {     "my-program" : "./path/to/program" }}
```
  man
  制订一个或通过数组制订一些文件来让linux下的man命令查找文档地址。
  如果只有一个文件被指定的话，装置后间接应用man+模块名称，而不论man指定的文件的理论名称。例如:
```
{"name" : "foo","version" : "1.2.3", "description" : "A packaged foo fooer for fooing foos", "main" : "foo.js", "man" : "./man/doc.1"}
```
  通过man foo命令会失去 ./man/doc.1 文件的内容。
  如果man文件名称不是以模块名称结尾的，装置的时候会给加上模块名称前缀。因而，上面这段配置：
```
{ "name" : "foo", "version" : "1.2.3", "description" : "A packaged foo fooer for fooing foos", "main" : "foo.js", "man" : [ "./man/foo.1", "./man/bar.1" ]}
```
  会创立一些文件来作为man foo和man foo-bar命令的后果。
  man文件必须以数字结尾，或者如果被压缩了，以.gz结尾。数字示意文件将被装置到man的哪个局部。
```
{ "name" : "foo", "version" : "1.2.3","description" : "A packaged foo fooer for fooing foos", "main" : "foo.js", "man" : [ "./man/foo.1", "./man/foo.2" ]}
```
  会创立 man foo 和 man 2 foo 两条命令。
  directories
  CommonJs通过directories来制订一些办法来形容模块的构造，看看npm的package.json文件https://registry.npmjs.org/npm/latest 。
  directories.lib
  通知用户模块中lib目录在哪，这个配置目前没有任何作用，然而对应用模块的人来说是一个很有用的信息。
  directories.bin
  如果你在这里指定了bin目录，这个配置上面的文件会被退出到bin门路下，如果你曾经在package.json中配置了bin目录，那么这里的配置将不起任何作用。
  directories.man
  指定一个目录，目录里边都是man文件，这是一种配置man文件的语法糖。
  directories.doc
  在这个目录里边放一些markdown文件，可能最终有一天它们会被敌对的展示进去（应该是在npm的网站上）
  directories.example
  放一些示例脚本，或者某一天会有用 - -！
  repository
  指定一个代码寄存地址，对想要为你的我的项目奉献代码的人有帮忙。像这样：
```
"repository" :{  "type" : "git",  "url" : "https://github.com/npm/npm.git"}
```

"repository" :
{

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

}

若你的模块放在GitHub, GitHub gist, Bitbucket, or GitLab的仓库里，npm install的时候能够应用缩写标记来实现：

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"

## scriptsscripts属性是一个对象，里边指定了我的项目的生命周期个各个环节须要执行的命令。key是生命周期中的事件，value是要执行的命令。具体的内容有 install start stop 等，详见[ https://docs.npmjs.com/misc/scripts](https://docs.npmjs.com/misc/scripts)## config用来设置一些我的项目不怎么变动的我的项目配置，例如port等。用户用的时候能够应用如下用法：

http.createServer(...).listen(process.env.npm_package_config_port)

能够通过npm config set foo:port 80来批改config。详见<https://docs.npmjs.com/misc/config>

{

"name" : "foo", "config" : { "port" : "8080" }

}

## dependenciesdependencies属性是一个对象，配置模块依赖的模块列表，key是模块名称，value是版本范畴，版本范畴是一个字符，能够被一个或多个空格宰割。dependencies也能够被指定为一个git地址或者一个压缩包地址。不要把测试工具或transpilers写到dependencies中。 上面是一些写法，详见<https://docs.npmjs.com/misc/semver>- version 准确匹配版本- \>version 必须大于某个版本- \>=version 大于等于- <version 小于- <=versionversion 小于- ~version "约等于"，具体规定详见semver文档- ^version "兼容版本"具体规定详见semver文档- 1.2.x 仅一点二点几的版本- http://... 见上面url作为denpendencies的阐明- - 任何版本- "" 空字符，和*雷同- version1 - version2 相当于 >=version1 <=version2.- range1 || range2 范畴1和范畴2满足任意一个都行- git... 见上面git url作为denpendencies的阐明- user/repo See 见上面GitHub仓库的阐明- tag 公布的一个非凡的标签，见npm-tag的文档 <https://docs.npmjs.com/getting-started/using-tags>- path/path/path 见上面本地模块的阐明  上面的写法都是能够的:

{ "dependencies" :
{ "foo" : "1.0.0 - 2.9999.9999"
, "bar" : ">=1.0.2 <2.1.2"
, "baz" : ">1.0.2 <=2.3.4"
, "boo" : "2.0.1"
, "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
, "asd" : "http://asdf.com/asdf.tar.gz"
, "til" : "~1.2"
, "elf" : "~1.2.3"
, "two" : "2.x"
, "thr" : "3.3.x"
, "lat" : "latest"
, "dyl" : "file:../dyl"
}
}

## URLs as Dependencies在版本范畴的中央能够写一个url指向一个压缩包，模块装置的时候会把这个压缩包下载下来装置到模块本地。## Git URLs as DependenciesGit url能够像上面一样:

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish 能够是任意标签，哈希值，或者能够检出的分支，默认是master分支。## GitHub URLs反对github的 username/modulename 的写法，#后边能够加后缀写明分支hash或标签：

{
"name": "foo",
"version": "0.0.0",
"dependencies": {

"express": "visionmedia/express","mocha": "visionmedia/mocha#4727d357ea"

}
}

## Local Pathsnpm2.0.0版本以上能够提供一个本地门路来装置一个本地的模块，通过npm install xxx --save 来装置，格局如下：

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

package.json 生成的相对路径如下:

{
"name": "baz",
"dependencies": {

"bar": "file:../foo/bar"

}
}

这种属性在离线开发或者测试须要用npm install的状况，又不想本人搞一个npm server的时候有用，然而公布模块到公共仓库时不应该应用这种属性。## devDependencies如果有人想要下载并应用你的模块，兴许他们并不心愿或须要下载一些你在开发过程中应用的额定的测试或者文档框架。在这种状况下，最好的办法是把这些依赖增加到devDependencies属性的对象中。这些模块会在npm link或者npm install的时候被装置，也能够像其余npm配置一样被治理，详见npm的config文档。对于一些跨平台的构建工作，例如把CoffeeScript编译成JavaScript，就能够通过在package.json的script属性里边配置prepublish脚本来实现这个工作，而后须要依赖的coffee-script模块就写在devDependencies属性种。例如:

{ "name": "ethopia-waza",
"description": "a delightfully fruity coffee varietal",
"version": "1.2.3",
"devDependencies": {

"coffee-script": "~1.6.3"

},
"scripts": {

"prepublish": "coffee -o lib/ -c src/waza.coffee"

},
"main": "lib/waza.js"
}

prepublish脚本会在公布之前运行，因而用户在应用之前就不必再本人去实现编译的过程了。在开发模式下，运行npm install也会执行这个脚本（见npm script文档），因而能够很不便的调试。## peerDependencies有时候做一些插件开发，比方grunt等工具的插件，它们往往是在grunt的某个版本的根底上开发的，而在他们的代码中并不会呈现require("grunt")这样的依赖，dependencies配置里边也不会写上grunt的依赖，为了阐明此模块只能作为插件跑在宿主的某个版本范畴下，能够配置peerDependencies：

{
"name": "tea-latte",
"version": "1.3.5",
"peerDependencies": {

"tea": "2.x"

}
}

下面这个配置确保再npm install的时候tea-latte会和2.x版本的tea一起装置，而且它们两个的依赖关系是同级的：├── tea-latte@1.3.5└── tea@2.2.0这个配置的目标是让npm晓得，如果要应用此插件模块，请确保装置了兼容版本的宿主模块。## bundledDependencies下面的单词少个d，写成bundleDependencies也能够。指定公布的时候会被一起打包的模块。## optionalDependencies如果一个依赖模块能够被应用， 同时你也心愿在该模块找不到或无奈获取时npm持续运行，你能够把这个模块依赖放到optionalDependencies配置中。这个配置的写法和dependencies的写法一样，不同的是这里边写的模块装置失败不会导致npm install失败。当然，这种模块就须要你本人在代码中解决模块的确的状况了，例如：

try {
var foo = require('foo')
var fooVersion = require('foo/package.json').version
} catch (er) {
foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
foo = null
}

// .. then later in your program ..

if (foo) {
foo.doFooThings()
}

optionalDependencies 中的配置会笼罩dependencies中的配置，最好只在一个中央写。## engines你能够指定我的项目运行的node版本范畴，如下：{ "engines" : { "node" : ">=0.10.3 <0.12" } }和dependencies一样，如果你不指定版本范畴或者指定为*，任何版本的node都能够。也能够指定一些npm版本能够正确的装置你的模块，例如：{ "engines" : { "npm" : "~1.0.20" } }要留神的是，除非你设置了engine-strict属性，engines属性是仅供参考的。## engineStrict留神：这个属性曾经弃用，将在npm 3.0.0 版本干掉。## os能够指定你的模块只能在哪个操作系统上跑："os" : [ "darwin", "linux" ]也能够指定黑名单而不是白名单："os" : [ "!win32" ]服务的操作系统是由process.platform来判断的，这个属性容许黑白名单同时存在，尽管没啥必要这样搞...## cpu限度模块只能在某某cpu架构下运行"cpu" : [ "x64", "ia32" ]同样能够设置黑名单:"cpu" : [ "!arm", "!mips" ]cpu架构通过 process.arch 判断## preferGlobal如果您的软件包次要用于装置到全局的命令行应用程序，那么该值设置为true ，如果它被装置在本地，则提供一个正告。实际上该配置并没有阻止用户把模块装置到本地，只是避免该模块被谬误的应用引起一些问题。## private如果这个属性被设置为true，npm将回绝公布它，这是为了避免一个公有模块被无意间公布进来。如果你只想让模块被公布到一个特定的npm仓库，如一个外部的仓库，可与在上面的publishConfig中配置仓库参数。## publishConfig这个配置是会在模块公布时用到的一些值的汇合。如果你不想模块被默认被标记为最新的，或者默认公布到公共仓库，能够在这里配置tag或仓库地址。## DEFAULT VALUESnpm设置了一些默认参数，如：`·"scripts": {"start": "node server.js"}`如果模块根目录下有一个`server.js文件`，那么npm start会默认运行这个文件。`"scripts":{"preinstall": "node-gyp rebuild"}`如果模块根目录下有`binding.gyp`, npm将默认用node-gyp来编译preinstall的脚本`"contributors": [...]`若模块根目录下有`AUTHORS` 文件，则npm会按Name (url)格局解析每一行的数据增加到`contributors`中，能够用#增加行正文.

概述

name

version

description

keywords

homepage

bugs

license

和用户相干的属性: author, contributors

files

main

bin

man

directories

directories.lib

directories.bin

directories.man

directories.doc

directories.example

repository