npm package.json字段全解

name

在package.json中最重要的就是name和version字段。他们都是必须的，若是没有就没法install。name和version一块儿组成的标识在假设中是惟一的。改变包应该同时改变version。

name是这个东西的名字。注意：

• 不要把node或者js放在名字中。由于你写了package.json它就被假定成为了js，不过你能够用"engine"字段指定一个引擎（见后文）。
• 这个名字会做为在URL的一部分、命令行的参数或者文件夹的名字。任何non-url-safe的字符都是不能用的。
• 这个名字可能会做为参数被传入require()，因此它应该比较短，但也要意义清晰。
• 在你爱上你的名字以前，你可能要去npm registry查看一下这个名字是否已经被使用了。 http://registry.npmjs.org/

version

在package.json中最重要的就是name和version字段。他们都是必须的，若是没有就没法install。name和version一块儿组成的标识在假设中是惟一的。改变包应该同时改变version。

version必须能被 node-semver解析，它被包在npm的依赖中。（要本身用能够执行npm install semver）

description

Put a description in it. It's a string. This helps people discover your package, as it's listed in npm search.

keywords

放简介，字符串。方便屌丝们在 npm search中搜索。

homepage

项目官网的url。

注意：这和“url”不同样。若是你放一个“url”字段，registry会觉得是一个跳转到你发布在其余地方的地址，而后喊你滚粗。 嗯，滚粗，没开玩笑。

嗯，滚粗，没开玩笑。

bugs

你项目的提交问题的url和（或）邮件地址。这对遇到问题的屌丝颇有帮助。

差很少长这样：

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

你能够指定一个或者指定两个。若是你只想提供一个url，那就不用对象了，字符串就行。

若是提供了url，它会被npm bugs命令使用。

license

你应该要指定一个许可证，让人知道使用的权利和限制的。

最简单的方法是，假如你用一个像BSD或者MIT这样通用的许可证，就只须要指定一个许可证的名字，像这样：

{ "license" : "BSD" }

若是你有更复杂的许可条件，或者想要提供给更多地细节，能够这样:

"licenses" : [
  { "type" : "MyLicense"
  , "url" : "http://github.com/owner/project/path/to/license"
  }
]

在根目录中提供一个许可证文件也蛮好的。

people fields: author, contributors

author是一我的。contributors是一堆人的数组。person是一个有name字段，可选的有url、email字段的对象，像这样：

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

或者能够把全部的东西都放到一个字符串里，npm会给你解析：

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

email和url在两种形式中都是可选的。

也能够在你的npm用户信息中设置一个顶级的maintainers字段。

files

files是一个包含项目中的文件的数组。若是命名了一个文件夹，那也会包含文件夹中的文件。（除非被其余条件忽略了）

你也能够提供一个.npmignore文件，让即便被包含在files字段中得文件被留下。其实就像.gitignore同样。

main

main字段是一个模块ID，它是一个指向你程序的主要项目。就是说，若是你包的名字叫foo，而后用户安装它，而后require("foo")，而后你的main模块的exports对象会被返回。

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

对于大多数模块，它是很是有意义的，其余的都没啥。

bin

不少包都有一个或多个可执行的文件但愿被放到PATH中。npm让妈妈不再用担忧了（实际上，就是这个功能让npm可执行的）。

要用这个功能，给package.json中的bin字段一个命令名到文件位置的map。初始化的时候npm会将他连接到prefix/bin（全局初始化）或者./node_modules/.bin/（本地初始化）。

好比，npm有：

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

因此，当你初始化npm，它会建立一个符号连接到cli.js脚本到/usr/local/bin/npm。

若是你只有一个可执行文件，而且名字和包名同样。那么你能够只用一个字符串，好比：

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

指定一个单一的文件或者一个文件数组供man程序使用。

若是只提供一个单一的文件，那么它初始化后就是man <pkgname>的结果，而无论实际的文件名是神马，好比：

{ "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文件了。

若是文件名不是以包名开头，那么它会被冠之前缀，下面的：

{ "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为后缀。The number dictates which man section the file is installed into.

{ "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 Packages规范说明了几种方式让你能够用directorieshash标示出包得结构。若是看一下npm's package.json，你会看到有directories标示出doc, lib, and man。

在将来，这个信息可能会被用到。

directories.lib

告诉屌丝们你的库文件夹在哪里。目前没有什么特别的东西须要用到lib文件夹，但确实是重要的元信息。

directories.bin

若是你指定一个“bin”目录，而后在那个文件夹中得全部文件都会被当作"bin"字段使用。

若是你已经指定了“bin”字段，那这个就无效。

directories.man

一个放满man页面的文件夹。贴心地建立一个“man”字段。
A folder that is full of man pages. Sugar to generate a "man" array by
walking the folder.

directories.doc

将markdown文件放在这里。最后，这些会被很好地展现出来，也许，某一天。
Put markdown files in here. Eventually, these will be displayed nicely,
maybe, someday.

directories.example

将事例脚本放在这里。某一天，它可能会以聪明的方式展现出来。

repository

指定你的代码存放的地方。这个对但愿贡献的人有帮助。若是git仓库在github上，那么npm docs命令能找到你。

这样作：

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

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

URL应该是公开的（即使是只读的）能直接被未通过修改的版本控制程序处理的url。不该该是一个html的项目页面。由于它是给计算机看的。

scripts

“scripts”是一个由脚本命令组成的hash对象，他们在包不一样的生命周期中被执行。key是生命周期事件，value是要运行的命令。

config

"config" hash能够用来配置用于包脚本中的跨版本参数。在实例中，若是一个包有下面的配置：

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

而后有一个“start”命令引用了npm_package_config_port环境变量，用户能够经过npm config set foo:port 8001来重写他。

dependencies

依赖是给一组包名指定版本范围的一个hash。这个版本范围是一个由一个或多个空格分隔的字符串。依赖还能够用tarball或者git URL。

请不要将测试或过渡性的依赖放在dependencies中。见下文的devDependencies。

• 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 URLs'

好比下面都是合法的：

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

依赖URL

能够指定一个tarball URL，这个tarball将在包被初始化的时候下载并初始化。

依赖Git URL

Git urls 能够是下面几种形式：

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是能够被git checkout的任何tag、sha或者branch。默认为master。

GitHub URLs

1.1.65版后，你能够仅仅用“user/foo-project”引用GitHub urls，好比：

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

devDependencies

若是有人要用你的模块，但他们可能不须要你开发所使用的外部测试或者文档框架。

在这种状况下，最好将这些附属的项目列在devDependencies中。

这些东西会在根目录执行npm link或者npm install的时候初始化，并能够像其余npm配置参数同样管理。

对于非特定平台的构建步骤，好比须要编译CoffeeScript，能够用prepublish脚本去实现，并把它依赖的包放在devDependency中。（译者注：prepublish定义了在执行npm publish的时候先行执行的脚本。详见scripts）

好比：

{ "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脚本会在publishing前运行，这样用户就不用本身去require来编译就能使用。而且在开发模式中（好比本地运行npm install）会运行这个脚本以便更好地测试。

peerDependencies

在一些场景中，如在一个host中没必要须进行require时候，你想表现你的package与一个host工具或者库的兼容关键。这通常用来引用插件。尤为是你的模块可能要暴露一个特定的接口，并由host文档来预期和指定。

好比：

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

这能保证你的package能够只和tea的2.x版本一块儿初始化。npm install tea-latte可能会产生下面的依赖关系

├── tea-latte@1.3.5
└── tea@2.2.0

试图初始化另外一个有会冲突的依赖的插件将致使一个错误。所以，确保你的插件的需求约束越弱越好，而不要去把它锁定到一个特定的版本。

假设这个host遵照semver规范，只改变这个package的主版本会打破你的插件。所以，若是你在package中用过每一个1.x版本，就用"^1.0"或者"1.x"来表示。若是你依赖于功能介绍1.5.2，用">= 1.5.2 < 2"。

bundledDependencies

一组包名，他们会在发布的时候被打包进去。

拼成"bundleDependencies"（缺d）也能够。

optionalDependencies

若是一个依赖可用，但你但愿在它安装错误的时候npm也能继续初始化，那么你能够把它放在optionalDependencies hash中。这是一个包名到版本或者url的map，就像dependencies hash同样。只是它运行错误。

处理缺少依赖也是你的程序的责任。好比像这样：

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

而且，像dependensies同样，若是你不指定版本或者指定“*”做为版本，那么全部版本的node均可以。

若是指定一个“engines”字段，那么npm会须要node在里面，若是“engines”被省略，npm会假定它在node上工做。

你也能够用“engines”字段来指定哪个npm版本能更好地初始化你的程序，如：

{ "engines" : { "npm" : "~1.0.20" } }

记住，除非用户设置engine-strict标记，这个字段只是建议值。

engineStrict

若是你肯定你的模块必定不会运行在你指定版本以外的node或者npm上，你能够在package.json文件中设置"engineStrict":true。它会重写用户的engine-strict设置。

除非你很是很是肯定，不然不要这样作。若是你的engines hash过分地限制，极可能轻易让本身陷入窘境。慎重地考虑这个选择。若是你们滥用它，它会再之后的npm版本中被删除。

os

你能够指定你的模块要运行在哪些操做系统中：

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

你也能够用黑名单代替白名单，在名字前面加上“!”就能够了：

"os" : [ "!win32" ]

操做系统用process.platform来探测。

虽然没有很好地理由，但它是同时支持黑名单和白名单的。

cpu

若是你的代码只能运行在特定的cpu架构下，你能够指定一个：

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

就像os选项，你也能够黑一个架构：

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

cpu架构用process.arch探测。

preferGlobal

若是包主要是须要全局安装的命令行程序，就设置它为true来提供一个warning给只在局部安装的人。

它不会真正的防止用户在局部安装，但若是它没有按预期工做它会帮助防止产生误会。

private

若是你设置"private": true，npm就不会发布它。

这是一个防止意外发布私有库的方式。若是你要肯定给定的包是只发布在特定registry（如内部registry）的，用publishConfighash的描述来重写registry的publish-time配置参数。

publishConfig

这是一个在publish-time使用的配置集合。当你想设置tag或者registry的时候它很是有用，因此你能够肯定一个给定的包没有打上“lastest”的tag或者被默认发布到全局的公开registry。

任何配置均可以被重写，但固然可能只有“tag”和“registry”与发布的意图有关。

DEFAULT VALUES

npm会根据包的内容设置一些默认值。

• "scripts": {"start": "node server.js"}

  若是包的根目录有server.js文件，npm会默认将start命令设置为node server.js。

• "scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}

  若是包的根目录有wscript文件，npm会默认将preinstall命令用node-waf进行编译。

• "scripts":{"preinstall": "node-gyp rebuild"}

  若是包的根目录有binding.gyp文件，npm会默认将preinstall命令用node-gyp进行编译。

• "contributors": [...]

  若是有AUTHORS文件，npm会默认逐行按Name <email> (url)格式处理，邮箱和url是可选的。#号和空格开头的行会被忽略。

参考网址1：http://www.mujiang.info/translation/npmjs/files/package.json.html

参考网址2：http://www.nopcn.com/post/npmjs-packagejson.aspx