npm package.json 备忘录

package.json

name (必需)

一些建议 * 不要在name里用js或者node * 使用对于url来说安全的字符,另外不要以.或者_开头。 * name很有可能作为require()的参数,因此ta应该比较短,但也可以自我描述。 * 在你过度使用一个name之前,先去检查他是否已经被人使用了。

name可以选择性地使用一个范围作为前缀,比如@myorg/mypackage。

version

version必须可以被node-semver解析

description

一个描述性的字符串,会被列在npm search中,来帮助别人发现你的包

keywords

一个字符串数组,会被列在npm search中,来帮助别人发现你的包

homepage

项目主页的url

注意homepage不等于url,如果

bugs

用于跟踪提交问题的url或者邮箱地址

{ "url" : "http://github.com/owner/project/issues"
, "email" : "project@hostname.com"
}

如果提供了url,这个url会用于npm bugs中。

license

你应该为你的包指定一个协议,来让人们知道如何使用你的包以及有什么限制。
最简单的方法是,假设你是用的是一个通用协议,比如BSD-3-Clause或者MIT,你只需要写上这些协议的标准SPDX ID这就可以了。

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

你可以在这里查询SPDX license ID的完整列表,当然你最好使用OSI认可的协议。

author, contributors, maintainers

author是一个人,contributors是一个人的数组,author是一个对象,带有name属性和可选的url和email属性,像这样:

{ "name" : "Barney Rubble"
, "email" : "b@rubble.com"
, "url" : "http://barnyrubble.tumblr.com/"
}

或者你可以把他们缩成一个字符串

"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"  

files

files是一个要引入文件的数组,如果你在这个数组里写入了一个文件夹,这个文件夹的所有文件会被引入。

你也可以在你包的根目录下提供一个.npmignore文件,ta像.gitignore一样工作。

main

bin

许多包都希望能把一个或多个可执行文件安装到环境变量中。
想要完成这件事,就要在package.json的bin中,提供一个命令行和本地文件的映射。
在安装这个包的时候,npm就会把这个文件软链到prefix/bin用于全局安装,或者软链到./node_modules/.bin/中用于本地安装。

举个例子:

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

如果你引入的可执行文件是自身就可以运行的,直接使用字符串指定即可。

man

单个文件或者一个文件数组用于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结尾。

比如

{ "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

repository

指定你的代码放在哪里,如果你的代码仓库在github,那么使用npm docs就可以找到你。

例如:

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

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

TA不应该是一个指向一个HTML页面的url,ta是为计算机准备的。

scripts

scripts应该是一个包含脚本文件的文件夹。
查看npm-scripts来找到书写package scripts的方法。

config

config设置一些在scripts里会使用到的参数。

dependencies

dependencies是一个对象,ta是一个包名到版本范围的映射。
版本范围是一个字符串,也可以是一个traball或者git URL。

  • version:必须完美匹配
  • >version:必须大于version
  • >=version:同上
  • <version:同上
  • <=version:同上
  • ~version:大约等于version
  • ^version:与version相兼容
  • 1.2.x:1.2.0, 1.2.1...但是没有1.3.0
  • http://...:一个url
  • *:匹配任何版本
  • "":和*一样
  • version1 - version2:等于>=version1 <=version2
  • range1 || range2:或关系,满足其一即可。
  • git...:git URL
  • user/repo:Github URL
  • tag:
  • 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"
  }
}

Git 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  

GitHub URL

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express"
  }
}

从2.0.0版本后,你可以为依赖包指定一个本地路径
比如:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

devDependencies

正在下载和使用你模块的人,可能不想或者不需要下载你的测试用例或者说明文档。

在这种情况下,你最好把这些东西指定在devDependencies里。

这些依赖会在包根目录npm install时被安装,也可以像其他npm设置参数那样被管理。查看npm-config获取更多信息。

peerDependencies

bundleDependencies

optionalDependencies

engines

你可以指定你的包工作的node版本

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

如果你指定了engines,npm会假设他工作在node上。
你也可以在engines里指定能够正确安装你的包的npm版本。

注意:除非在config里制定了"engine-strict": true,这个部分指定的只作为一个建议。

os

指定你的模块运行的操作系统

"os" : [ "darwin", "linux" ]  

你也可以把一些操作系统列入黑名单

"os" : [ "!win32" ]  

cpu

指定你的模块能够运行的cpu架构

"cpu" : [ "x64", "ia32" ]  

黑名单

"cpu" : [ "!arm", "!mips" ]  

preferGlobal

是否支持全局安装,true为支持。

private