怎样运用package.json文件

2019年8月31日 214次阅读 来源: willhu

怎样运用package.json文件

最近在整顿之前写的模块的时刻，发明许多模块的package.json写的并非那末范例，所以查阅了一些材料，了解了一下关于怎样运用package.json，列出来供人人参考

本文参考了这三篇文章

属性列表

概述

这篇文档通知了你package.json内里，包括了那些字段。这个文件必需是个json文件，而不仅是一个js对象。文档中许多属性和设置能够经由过程npm-config来天生。

name（必填字段）

package.json中有两个字段是必填字段。name字段和version字段。缺乏这两个字段则没法装置npm模块。每一个npm模块也是依靠这两个字段作为唯一标识。假如你的npm模块有所修正，那末对应的version字段也应当有所转变。

name字段就是你的npm模块的称号。

name字段须要相符以下划定规矩：

  • name必需<= 214 个字节，包括模块的前缀

  • 不得以“_” 也许 “.” 作为name的开首

  • 不能有大写字符

  • 由于name字段会成为URL的一部份，或是敕令行的一个实参，也有多是个文件夹的名字，所以不能包括no-URL-safe(URL不法)字符。

一些发起：

  • 不要用和node中心模块一样的称号

  • 不要把“js”和”node”字段包括在name中。由于你现实在编写json文件，而包括这些字段会被以为是个js文件而非npm模块，假如你须要指定某些引擎的话，能够在“engines”字段中填写。

  • name会被写在require()的参数中，所以name最好简短且明白。

  • 建立一个name的时刻，最好去https://www.npmjs.com/查查称号是不是被占用。

name能够有一些前缀如 比方 @myorg/mypackage.能够在npm-scope的中检察概况。

version（必填字段）

package.json中有两个字段是必填字段。name字段和version字段。缺乏这两个字段则没法装置npm模块。每一个npm模块也是依靠这两个字段作为唯一标识。假如你的npm模块有所修正，那末对应的version字段也应当有所转变。

version字段必需能够被node-semver这个模块剖析，是个和npm绑缚在一同的包。

这里有关于版本号情势的寄义nodejs中每一个版本情势的寄义

description

一段字符串，用来形貌这个npm模块的作用，经由过程npm search的时刻回用到。

keywords

一个由字符串组成的数组，也有助于他人经由过程npm search的时刻疾速找到你的包。

homepage

这个项目标主页URL。 注重：这里和url属性不是一个东西，假如你填了url属性，npm的注册东西会以为你把项目宣布到别的处所了，就不会去npm官方堆栈去找。

bugs

包括你的项目标issue和email地点，假如他人在运用你的包的时刻遇到了题目，能够经由过程这里找到你并提交题目。

它的名堂以下：

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

url和email你能够选填个中一个也许两个，假如只填一个，能够直接写成字符串，而不是一个对象。

假如供应了url, 运用npm bugs敕令的时刻会用到。

license

给你的模块定一个协定，让人人晓得这个模块的运用权限。比方：遵照BSD-2-Clause or MIT协定。增加一个SPDX许可以下：


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

这里检察SPDX协定完全列表。抱负状况下，你应当选一个OSI许可（开源许可）。

假如你的模块遵照多种许可，能够运用SPDX协定2.0的语法，以下：


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

假如你运用的是许可证还没有分派一个SPDX标识符,也许假如您运用的是一个定制的许可证,运用如许的字符串值:


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

然后在模块的顶部include 这个<filename>的文件。

一些旧的模块运用许可对象或一个“许可证”属性,个中包括许可对象数组:

// Not valid metadata
{ "license" :
  { "type" : "ISC"
  , "url" : "http://opensource.org/licenses/ISC"
  }
}
// Not valid metadata
{ "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,来防备模块的不测宣布

people fields: author, contributors

用户相干的属性：author是一个作者，contributors是一个包括一堆作者的数组。每一个person有一些形貌的字段，以下：

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

file字段是一个包括在你项目里的文件的数组，内里的内容是文件名也许文件夹名。假如是文件夹，那末内里的文件也会被包括进来,除非你设置了ignore划定规矩。
你也能够在模块根目次下建立一个”.npmignore”文件（windows下没法直接建立以”.”开首的文件，运用linux敕令行东西建立如git bash），写在这个文件里边的文件即使被写在files属性里边也会被消除在外，这个文件的写法”.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”)来援用该模块，返回的内容就是你的模块的 module.exports指向的对象。

这是一个相关于你的模块文件夹的模块ID，关于大多数的模块，有个主剧本就足够了。

bin

许多模块有一个或多个可实行文件须要设置到PATH途径下。npm就是经由过程这个特征装置，使得npm可实行。

要用这个功用，给package.json中的bin字段一个敕令名到文件位置的map。初始化的时刻npm会将他链接到prefix/bin（全局初始化）也许./node_modules/.bin/（当地初始化）。

比方：一个myapp模块多是如许：

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

所以，当你装置myapp，npm会从cli.js文件建立一个到/usr/local/bin/myapp途径下。

假如你只要一个可实行文件，而且名字和包名一样。那末你能够只用一个字符串，比方：

{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }

和下面是一样的效果：

, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }

man

用来给Linux下的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 文件的内容。
假如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文件npm’s package.json ，会看到有directories标示出doc, lib, and man。

现在这个设置没有任何作用，未来能够会整出一些名堂来。

directories.lib

通知用户模块中lib目次在哪，这个设置现在没有任何作用，然则对运用模块的人来说是一个很有效的信息。

directories.bin

假如你在这里指定了bin目次，这个设置下面的文件会被加入到bin途径下，假如你已在package.json中设置了bin目次，那末这里的设置将不起任何作用。

directories.man

指定一个目次，目次里边都是man文件，这是一种设置man文件的语法糖。

directories.doc

在这个目次里边放一些markdown文件，能够终究有一天它们会被友爱的展示出来（应当是在npm的网站上）

directories.example

放一些示例剧本，也许某一天会有效 – -！

repository

指定你的代码寄存的处所。这个对愿望孝敬的人有协助。假如git堆栈在github上，那末npm docs敕令能找到你。

以下：

"repository" :
  { "type" : "git"
  , "url" : "https://github.com/npm/npm.git"
  }
"repository" :
  { "type" : "svn"
  , "url" : "https://v8.googlecode.com/svn/trunk/"
  }

URL应当是公然的（即使是只读的）能直接被未经由修正的版本控制顺序处置惩罚的url。不该当是一个html的项目页面。由于它是给计算机看的。

若你的模块放在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 等，详见npm-scripts.

config

用来设置一些项目不怎么变化，跨版本的项目设置，比方port等。
用法以下：

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

然后有一个start敕令援用npm_package_config_port环境变量，用户也能够用以下体式格局改写：npm config set foo:port 8001

See npm-config and npm-scripts for more on package configs.

dependencies

dependencies属性是一个对象，设置模块依靠的模块列表，key是模块称号，value是版本局限，版本局限是一个字符，能够被一个或多个空格支解。

dependencies也能够被指定为一个git地点也许一个紧缩包地点。

不要把测试东西或transpilers写到dependencies中。 对照下面的devDependencies。

下面是一些写法，详见https://docs.npmjs.com/misc/s…

  • 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/gettin…

  • 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依靠

在版本局限的处所能够写一个url指向一个紧缩包，模块装置的时刻会把这个紧缩包下载下来装置到模块当地。

Git URLs依靠

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 能够是恣意tag，hash，也许能够检出的分支，默许是master分支。

github URLs

支撑github的 username/modulename 的写法，#后边能够加后缀写明分支hash或标签,以下：

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

当地途径

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剧本会在publishing前运转，如许用户就不必自身去require来编译就可以运用。而且在开辟形式中（比方当地运转npm install）会运转这个剧本以便更好地测试。

peerDependencies

偶然，你的项目和所依靠的模块，都邑同时依靠另一个模块，然则所依靠的版本不一样。比方，你的项目依靠A模块和B模块的1.0版，而A模块自身又依靠B模块的2.0版。

大多数状况下，这不组成题目，B模块的两个版本能够并存，同时运转。然则，有一种状况，会出现题目，就是这类依靠关联将暴露给用户。

最典范的场景就是插件，比方A模块是B模块的插件。用户装置的B模块是1.0版本，然则A插件只能和2.0版本的B模块一同运用。这时候，用户如果将1.0版本的B的实例传给A，就会出现题目。因而，须要一种机制，在模板装置的时刻提示用户，假如A和B一同装置，那末B必需是2.0模块。

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

指定宣布的时刻会被一同打包的模块。

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标记，F不然这个字段只是发起值。

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，就会供应一个warning，如许来只在部分装置的人会获得这个warning。

它不会真正的防备用户在部分装置，只是防备该模块被毛病的运用引发一些题目。

private

假如这个属性被设置为true，npm将不会宣布它。

这是为了防备一个私有模块被无意间宣布出去。假如你想让模块被宣布到一个特定的npm堆栈，如一个内部的堆栈，可与鄙人面的publishConfig中设置堆栈参数。

publishConfig

这是一个在publish-time时会用到的设置鸠合。当你想设置tag、registry或access时迥殊有效，所以你能够确保一个给定的包没法在没有被打上”latest”标记时就被宣布到全局大众的registry。

任何设置都能够被掩盖，固然能够只要”tag”, “registry”和”access”和宣布企图有关。

参考npm-config来检察那些能够被掩盖的设置项列表。

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中，能够用#增加行解释

参考材料

    原文作者：willhu
    原文地址: https://segmentfault.com/a/1190000007777410
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞