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

概述

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

<!– more –>

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”

## scripts

scripts 属性是一个对象，里边指定了我的项目的生命周期个各个环节须要执行的命令。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"}

}

## dependencies

dependencies 属性是一个对象，配置模块依赖的模块列表，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 Dependencies

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

commit-ish 能够是任意标签，哈希值，或者能够检出的分支，默认是 master 分支。## GitHub URLs

反对 github 的 username/modulename 的写法，# 后边能够加后缀写明分支 hash 或标签：

{
“name”: “foo”,
“version”: “0.0.0”,
“dependencies”: {

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

}
}

## Local Paths

npm2.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 VALUES

npm 设置了一些默认参数，如：`·"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` 中，能够用 #增加行正文.