package.json配置详解

name

在大多数在你的package.json重要的事情是名称和版本字段。这些实际上是必需的，没有它们，您的软件包将无法安装。名称和版本一起构成一个标识符，该标识符被认为是完全唯一的。对软件包的更改应与版本的更改同时进行。

名字就是你的名字。

一些规则：

名称必须少于或等于214个字符。这包括范围包的范围。
名称不能以点或下划线开头。
新软件包名称中不得包含大写字母。
该名称最终成为URL，命令行参数和文件夹名称的一部分。因此，该名称不能包含任何非URL安全的字符。

一些技巧：

不要使用与核心Node模块相同的名称。
不要在名称中添加“ js”或“ node”。假设它是js，因为您正在编写package.json文件，并且可以使用“ engines”字段指定引擎。（见下文。）
该名称可能会作为参数传递给require（），因此它应该简短一些，但也应具有合理的描述性。
您可能需要检查npm注册表，以查看是否已经有该名称的东西，然后再附加它。https://www.npmjs.com/

名称可以可选地以范围为前缀，例如@myorg/mypackage。请参阅 npm-scope以获取更多详细信息。

version

在大多数在你的package.json重要的事情是名称和版本字段。这些实际上是必需的，没有它们，您的软件包将无法安装。名称和版本一起构成一个标识符，该标识符被认为是完全唯一的。对软件包的更改应与版本的更改同时进行。

版本必须可以由node-semver解析，它与npm捆绑在一起作为依赖项。（npm install semver自己使用）。

有关版本号和范围的更多信息，请参见semver。

description

在其中添加描述。这是一个字符串。如中所列，这可以帮助人们发现您的包

keywords

在其中放入关键字。它是一个字符串数组。这可以帮助人们发现您的软件包

homepage

项目首页的网址

bugs

项目的问题跟踪器的URL和/或应向其报告问题的电子邮件地址。这些对于遇到您的包问题的人很有帮助。

它看起来应该像这样：

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

您可以指定一个或两个值。如果您只想提供一个url，则可以将“ bugs”的值指定为简单字符串而不是对象。

如果提供了URL，则该npm bugs命令将使用它。

license

您应该为包指定许可证，以便人们知道如何使用它们以及您对该包裹施加的任何限制。

如果您使用的是通用许可证，例如BSD-2-Clause或MIT，请为所使用的许可证添加当前SPDX许可证标识符，如下所示：

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

您可以查看SPDX许可证ID的完整列表。理想情况下，您应该选择经过 OSI批准的产品。

如果您的软件包已获得多个通用许可证的许可，请使用SPDX许可证表达式语法版本2.0字符串，如下所示：

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

如果使用的许可证尚未分配SPDX标识符，或者使用的是自定义许可证，请使用如下所示的字符串值：

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

然后<filename>，在包的顶层添加一个名为的文件。

一些旧软件包使用许可证对象或包含许可证对象数组的“ licenses”属性：

// Not valid metadata
{
  "license": {
    "type": "ISC",
    "url": "https://opensource.org/licenses/ISC"
  }
}
// Not valid metadata
{
  "licenses": [
    {
      "type": "MIT",
      "url": "https://www.opensource.org/licenses/mit-license.php"
    },
    {
      "type": "Apache-2.0",
      "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}

这些样式现已弃用。而是使用SPDX表达式，如下所示：

{ "license": "ISC" }

{ "license": "(MIT OR Apache-2.0)" }

最后，如果您不希望以任何条款授予他人使用私有或未发布软件包的权利：

{ "license": "UNLICENSED" }

还考虑进行设置"private": true以防止意外发布。

author, contributors

“作者”是一个人。“贡献者”是一群人。“人员”是具有“名称”字段以及（可选）“ url”和“ email”的对象，如下所示：

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

或者，您可以将所有内容缩短为一个字符串，然后npm会为您解析：

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

电子邮件和url都是可选的。

npm还会为您的npm用户信息设置一个顶级“ maintainers”字段。

files

可选的“files”字段是文件模式的数组，描述了将软件包作为依赖项安装时要包括的条目。如果省略files数组，则除自动排除的文件外的所有内容都将包含在您的发布中。如果在数组中命名文件夹，则该文件还将包括该文件夹中的文件（除非本节中的另一条规则将忽略它们）。

您还可以.npmignore在包的根目录或子目录中提供文件，以防止文件被包含。在程序包的根目录下，它不会覆盖“files”字段，但在子目录中，它将覆盖。该.npmignore文件的工作方式与一样 .gitignore。如果有.gitignore文件但.npmignore缺少文件，.gitignore则将使用的内容。

无论设置如何，总是会包含某些文件：

package.json
README
CHANGES / CHANGELOG / HISTORY
LICENSE / LICENCE
NOTICE
“main”字段中的文件

README，CHANGES，LICENSE和NOTICE可以有任何情况下和延伸。

相反，某些文件总是被忽略：

.git
CVS
.svn
.hg
.lock-wscript
.wafpickle-N
.*.swp
.DS_Store
._*
npm-debug.log
.npmrc
node_modules
config.gypi
*.orig
package-lock.json （改用收缩包装）

main

模块ID，它是程序的主要入口点。也就是说，如果您的包名为foo，并且用户先安装它，然后执行 require("foo")，则将返回主模块的导出对象。

这应该是相对于软件包文件夹根目录的模块ID。

对于大多数模块，拥有一个主脚本是最有意义的，而通常没有太多其他东西。

bin

许多软件包都具有一个或多个要安装到PATH中的可执行文件。npm使此操作非常容易（实际上，它使用此功能来安装“ npm”可执行文件。）

要使用此功能，请bin在package.json中提供一个字段，该字段是命令名到本地文件名的映射。在安装时，npm会将文件符号链接到 prefix/bin以进行全局安装或./node_modules/.bin/本地安装。

例如，myapp可能具有以下内容：

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

因此，当您安装myapp时，它将创建从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"
  }
}

请确保您引用的文件以bin开头 #!/usr/bin/env node，否则脚本将在没有node可执行文件的情况下启动！

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/doc.1文件，使其成为目标man foo

如果文件名不是以程序包名称开头的，则使用前缀。所以这：

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

手册文件必须以数字结尾，.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

directorys

CommonJS Packages规范详细介绍了几种使用directories 对象指示软件包结构的方法。如果查看npm的package.json，则会看到它具有doc，lib和man的目录。

lib

告诉人们您的lib大部分在哪里。对于lib文件夹，没有什么特别的事情，但这是有用的元信息。

bin

如果在中指定bin目录directories.bin，则将添加该文件夹中的所有文件。

由于该bin指令的工作方式，同时指定 bin路径和设置directories.bin是错误的。如果要指定单个文件，请使用bin，对于现有bin目录中的所有文件，请使用directories.bin。

man

一个充满man页的文件夹。糖通过遍历文件夹来生成“ man”数组。

doc

将markdown文件放在这里

example

示例脚本

test

测试

repository

指定代码所在的位置。这对想要贡献的人很有帮助。如果git repo在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，可以直接将其传递给VCS程序，而无需进行任何修改。它不应是您放入浏览器中的html项目页面的url。它用于计算机。

对于GitHub，GitHub gist，Bitbucket或GitLab存储库，您可以使用与以下相同的快捷方式语法npm install：

"repository": "npm/npm"

"repository": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

scripts

“ scripts”属性是一个字典，其中包含在包的生命周期中的各个时间运行的脚本命令。关键是生命周期事件，该值是在该点运行的命令。

请参阅参考资料，npm-scripts以了解有关编写程序包脚本的更多信息。

config

“ config”对象可用于设置软件包脚本中使用的配置参数，这些配置脚本会在升级期间持续存在。例如，如果一个程序包具有以下内容：

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

然后有一个“开始”命令，该命令随后引用了 npm_package_config_port环境变量，那么用户可以通过执行来覆盖它npm config set foo:port 8001。

有关软件包配置的更多信息，请参见npm-config和npm-scripts。

dependencies

依赖关系在一个简单的对象中指定，该对象将程序包名称映射到版本范围。版本范围是一个具有一个或多个以空格分隔的描述符的字符串。依赖关系也可以通过tarball或git URL进行标识。

请不要在您的dependencies物体中放置测试线束或编译器。 请参阅devDependencies下面的。

有关指定版本范围的更多详细信息，请参见semver。

version必须version完全匹配
>version 必须大于 version
>=version 等等
<version
<=version
~version“大约等效于版本”请参见semver
^version“与版本兼容”请参见semver
1.2.x 1.2.0、1.2.1等，但不是1.3.0
http://... 请参阅下面的“ URL作为依赖项”
* 匹配任何版本
"" （只是一个空字符串）与 *
version1 - version2与相同>=version1 <=version2。
range1 || range2 如果满足range1或range2，则通过。
git... 请参阅下面的“将Git URL作为依赖项”
user/repo 请参阅下面的“ GitHub URL”
tag标记并发布为tag See的特定版本npm-dist-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"
  }
}

URL作为依赖项

您可以指定tarball URL代替版本范围。

该压缩包将在安装时下载并本地安装到您的软件包中。

Git URL作为依赖项

Git URL的形式为：

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

<protocol>是以下之一git，git+ssh，git+http，git+https，或 git+file。

如果#<commit-ish>提供，它将用于精确克隆该提交。如果commit-ish的格式为#semver:<semver>，<semver>可以是任何有效的semver范围或确切的版本，并且npm会在远程存储库中查找与该范围匹配的任何标记或引用，就像对注册表依赖项一样。如果未指定#<commit-ish>或#semver:<semver>，则master使用。

例子：

git+ssh://git@github.com:npm/npm.git#v1.0.27
git+ssh://git@github.com:npm/npm#semver:^5.0
git+https://isaacs@github.com/npm/npm.git
git://github.com/npm/npm.git#v1.0.27

GitHub网址

从1.1.65版本开始，您可以将GitHub URL简称为“ foo”：“ user / foo-project”。与git URL一样，commit-ish可以包含后缀。例如：

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "expressjs/express",
    "mocha": "mochajs/mocha#4727d357ea",
    "module": "user/repo#feature\/branch"
  }
}

本地路径

从2.0.0版开始，您可以提供包含软件包的本地目录的路径。可以使用npm install -S或 npm install --save使用以下任意形式保存本地路径：

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

在这种情况下，它们将被规范化为相对路径并添加到您的中 package.json。例如：

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

此功能对于本地脱机开发和创建需要npm安装的测试很有用，您不想在不打外部服务器的地方安装npm，但是在将程序包发布到公共注册表时不应使用。

devDependencies

如果某人打算在程序中下载和使用您的模块，那么他们可能不希望或不需要下载并构建您使用的外部测试或文档框架。

在这种情况下，最好将这些其他项目映射到一个devDependencies 对象中。

这些东西将在安装时npm link或npm install 从软件包的根目录安装，并且可以像其他任何npm配置参数一样进行管理。有关npm-config更多信息，请参见。

对于不是特定于平台的构建步骤（例如，将CoffeeScript或其他语言编译为JavaScript），请使用prepare 脚本来执行此操作，并使所需的软件包成为devDependency。

例如：

{
  "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepare": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

该prepare脚本将在发布之前运行，因此用户可以使用该功能而无需他们自己对其进行编译。在开发人员模式下（即在本地运行npm install），它也会同时运行此脚本，以便您可以轻松对其进行测试。

peerDependencies

在某些情况下，您想表达软件包与主机工具或库的兼容性，而不必一定要require对此主机进行操作。通常将其称为插件。值得注意的是，您的模块可能正在公开主机文档预期和指定的特定接口。

例如：

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

这样可以确保您的软件包tea-latte只能与主机软件包的第二个主要版本一起安装tea。npm install tea-latte可能会产生以下依赖关系图：

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

注意：peerDependencies如果在依赖关系树中未显式依赖更高版本的npm版本1和2 ，它们将自动安装。在npm的下一个主要版本（npm @ 3）中，将不再是这种情况。您将收到一条警告，提示您未安装peerDependency。npms 1和2中的行为经常令人困惑，很容易使您陷入依赖地狱，npm旨在尽可能避免这种情况。

尝试安装其他要求冲突的插件会导致错误。因此，请确保您的插件要求尽可能广泛，并且不要将其锁定在特定的补丁程序版本中。

假设主机符合semver，则只有主机软件包主要版本中的更改会破坏您的插件。因此，如果您使用过主机软件包的每个1.x版本，请使用"^1.0"或"1.x"表示这一点。如果您依赖1.5.2中引入的功能，请使用">= 1.5.2 < 2"。

bundledDependencies

这定义了一组软件包名称，这些软件包名称将在发布软件包时捆绑在一起。

如果您需要在本地保留npm软件包或通过单个文件下载获得它们，则可以通过在bundledDependencies 数组中指定软件包名称并执行来将软件包捆绑在tarball文件中npm pack。

例如：

如果我们这样定义package.json：

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    "renderized", "super-streams"
  ]
}

我们可以awesome-web-framework-1.0.0.tgz通过运行获取文件npm pack。此文件包含的依赖关系renderized，并super-streams可以通过执行安装在一个新的项目npm install awesome-web-framework-1.0.0.tgz。

如果这是拼写的"bundleDependencies"，那么也很荣幸。

optionalDependencies

如果可以使用依赖项，但是如果找不到或无法安装npm，则希望npm继续进行，则可以将其放在optionalDependencies 对象中。这是程序包名称到版本或url的映射，就像 dependencies对象一样。区别在于构建失败不会导致安装失败。

处理依赖关系的缺失仍然是程序的责任。例如，如下所示：

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

并且，与依赖项一样，如果您不指定版本（或者如果您指定“ *”作为版本），那么任何版本的节点都可以。

如果您指定“engines”字段，则npm将要求“node”在该列表中的某个位置。如果省略了“ engines”，那么npm只会假设它可以在node上运行。

您还可以使用“engines”字段来指定哪些版本的npm能够正确安装程序。例如：

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

除非用户设置了engine-strictconfig标志，否则此字段仅供参考，并且仅在将软件包作为依赖项安装时才产生警告。

os

您可以指定模块将在哪些操作系统上运行：

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

您也可以将操作系统列入黑名单而不是白名单，只需在黑名单的操作系统前面加上“！”即可：

"os" : [ "!win32" ]

主机操作系统由 process.platform

尽管没有充分的理由这样做，但允许将其列入黑名单和白名单。

cpu

如果您的代码仅在某些cpu体系结构上运行，则可以指定哪些体系结构。

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

像该os选项一样，您也可以将体系结构列入黑名单：

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

主机架构由 process.arch

private

如果"private": true在package.json中设置，则npm将拒绝发布它。

这是防止意外发布私有存储库的方法。如果要确保仅将给定的程序包发布到特定的注册表（例如，内部注册表），请使用publishConfig下面描述的字典registry在发布时覆盖config参数。

publishConfig

这是将在发布时使用的一组配置值。如果要设置标签，注册表或访问权限，这特别方便，这样可以确保给定的程序包不标记为“最新”，不发布到全局公共注册表，或者默认情况下作用域模块是私有的。

可以覆盖任何配置值，但是出于发布的目的，当然只有“标签”，“注册表”和“访问”可能很重要。

请参阅npm-config以查看可以覆盖的配置选项列表。