package.json配置的一些说明

本是古典何须时尚 2024-04-18 12:31 67阅读 0赞

## 说明§ ##

您需要了解本文档，以了解package.json文件中的所需内容。它必须是实际的JSON，而不仅仅是JavaScript对象文字。

本文档中描述的许多行为都受到中描述的配置设置的影响`npm-config`。

## 名称§ ##

如果您计划发布包，则package.json中*最*重要的内容是名称和版本字段，因为它们是必需的。名称和版本一起形成一个假定完全唯一的标识符。对程序包的更改应随更改版本一起提供。如果您不打算发布包，则名称和版本字段是可选的。

这个名字就是你的名字。

一些规则：

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

一些技巧：

*  请勿使用与核心节点模块相同的名称。
 *  不要在名称中加上“js”或“node”。假设它是js，因为你正在编写一个package.json文件，你可以使用“engines”字段指定引擎。（见下文。）
 *  该名称可能作为参数传递给require（），因此它应该是简短的，但也是合理描述的。
 *  你可能想要检查npm注册表，看看是否已经有了这个名称的东西，然后再过于依赖它了。[https://www.npmjs.com/][https_www.npmjs.com]

名称可以选择以作用域为前缀，例如`@myorg/mypackage`。有关`npm-scope`详细信息，请参阅

## 版本§ ##

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

有关semver版本号和范围的更多信息。

## 说明§ ##

在其中加入说明。这是一个字符串。这可以帮助人们发现您的包裹，如下所示`npm search`。

## 关键词§ ##

将关键字放入其中。这是一个字符串数组。这有助于人们发现您列出的包裹`npm search`。

## 主页§ ##

项目主页的网址。

例：

"homepage": "https://github.com/owner/project#readme"

## 错误§ ##

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

它应该如下所示：

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

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

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

## 许可§ ##

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

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

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

您可以查看[SPDX许可证ID的完整列表][SPDX_ID]。理想情况下，您应该选择一个 [OSI][]批准的。

如果您的软件包在多个常见许可证下获得许可，请使用[SPDX许可证表达式语法版本2.0字符串][SPDX_2.0]，如下所示：

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

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

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

然后包含一个`<filename>`在包的顶层命名的文件。

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

// 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`以防止意外发布。

## 人物领域：作者，贡献者§ ##

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

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

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

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

电子邮件和网址都是可选的。

npm还会使用您的npm用户信息设置顶级“维护者”字段。

## 档案§ ##

可选`files`字段是一个文件模式数组，描述了将软件包作为依赖项安装时要包含的条目。文件模式遵循类似的语法`.gitignore`，但相反的：包括文件，目录或glob模式（`*`，`**/*`，和这样的）将让这个文件包含在压缩包时，它的包装。省略该字段将使其默认为`["*"]`，这意味着它将包含所有文件。

无论`files`数组中是否存在某些特殊文件和目录（见下文），也会包含或排除这些文件和目录。

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

文件包含了“的package.json＃文件”栏中*不能*被排除通过`.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` （使用shrinkwrap代替）

## 主要§ ##

主要字段是模块ID，它是程序的主要入口点。也就是说，如果您的软件包已命名`foo`，并且用户安装了该软件包，然后安装了该 软件包`require("foo")`，那么将返回您的主模块的exports对象。

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

对于大多数模块而言，最有意义的是拥有一个主脚本并且通常没有其他内容。

## 浏览器§ ##

如果您的模块用于客户端，则应使用浏览器字段而不是主字段。这有助于提示用户它可能依赖于Node.js模块中不可用的基元。（例如`window`）

## 彬§ ##

很多软件包都有一个或多个可以安装到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`

## 男人§ ##

指定单个文件或文件名数组，以便 `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`。

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`

## 目录§ ##

CommonJS [Packages][]规范详细介绍了使用`directories` 对象指示包结构的几种方法。如果你看一下[npm的package.json][npm_package.json]，你会看到它有doc，lib和man的目录。

将来，此信息可能会以其他创造性方式使用。

### directories.lib § ###

告诉人们您图书馆的大部分内容。lib文件夹没有任何特殊功能，但它是有用的元信息。

### directories.bin § ###

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

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

### 目录.man§ ###

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

### directories.doc § ###

将markdown文件放在这里。最终，这些将会很好地显示，也许有一天会显示出来。

### directories.example § ###

将示例脚本放在这里。总有一天，它可能会以某种巧妙的方式暴露出来。

### 目录。测试§ ###

把测试放在这里。它目前尚未公开，但可能在未来。

## 存储库§ ##

指定代码所在的位置。这对想要贡献的人很有帮助。如果git repo在GitHub上，那么该`npm docs` 命令将能够找到你。

像这样做：

"repository": {
         
      "type" : "git",
      "url" : "https://github.com/npm/cli.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"

如果`package.json`您的包不在根目录中（例如，如果它是monorepo的一部分），您可以指定它所在的目录：

"repository": {
         
      "type" : "git",
      "url" : "https://github.com/facebook/react.git",
      "directory": "packages/react-dom"
    }

## 脚本§ ##

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

请参阅`npm-scripts`以了解有关编写包脚本的更多信息。

## 配置§ ##

“config”对象可用于设置在升级过程中持久存在的程序包脚本中使用的配置参数。例如，如果包具有以下内容：

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

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

见`npm-config`和`npm-scripts`更多的软件包CONFIGS。

## 依赖性§ ##

依赖关系在将包名称映射到版本范围的简单对象中指定。版本范围是一个字符串，其中包含一个或多个以空格分隔的描述符。也可以使用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 as Dependencies”
 * `user/repo` 请参阅下面的“GitHub网址”
 * `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来代替版本范围。

这个tarball将在安装时下载并安装在您的软件包本地。

### Git URL作为依赖关系§ ###

Git网址的形式如下：

<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/cli.git#v1.0.27
    git+ssh://git@github.com:npm/cli#semver:^5.0
    git+https://isaacs@github.com/npm/cli.git
    git://github.com/npm/cli.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安装的测试，您不希望在其中访问外部服务器，但在将包发布到公共注册表时不应使用此功能。

## 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 § ##

In some cases, you want to express the compatibility of your package with a host tool or library, while not necessarily doing a `require` of this host. This is usually referred to as a *plugin*. Notably, your module may be exposing a specific interface, expected and specified by the host documentation.

For example:

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

This ensures your package `tea-latte` can be installed *along* with the second major version of the host package `tea` only. `npm install tea-latte` could possibly yield the following dependency graph:

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

**NOTE: npm versions 1 and 2 will automatically install `peerDependencies` if they are not explicitly depended upon higher in the dependency tree. In the next major version of npm (npm@3), this will no longer be the case. You will receive a warning that the peerDependency is not installed instead.** The behavior in npms 1 & 2 was frequently confusing and could easily put you into dependency hell, a situation that npm is designed to avoid as much as possible.

Trying to install another plugin with a conflicting requirement will cause an error. For this reason, make sure your plugin requirement is as broad as possible, and not to lock it down to specific patch versions.

假设主机符合[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`。请注意，程序包名称不包含任何版本，因为指定了该信息`dependencies`。

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

## optionalDependencies § ##

如果可以使用依赖项，但是如果无法找到或无法安装，您希望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" : ">=0.10.3 <0.12" } }

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

如果指定“引擎”字段，则npm将要求“节点”位于该列表的某个位置。如果省略“引擎”，则npm将假定它在节点上工作。

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

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

除非用户已设置`engine-strict`配置标志，否则此字段仅供参考，并且仅在将软件包安装为依赖项时才会生成警告。

## engineStrict § ##

**此功能已在npm 3.0.0中删除**

在npm 3.0.0之前，此功能用于处理此包，就像用户已设置一样`engine-strict`。它已不再使用。

## OS § ##

您可以指定模块将运行的操作系统：

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

你也可以黑名单而不是白名单操作系统，只需在黑名单操作系统前加上'！'：

"os" : [ "!win32" ]

主机操作系统由确定 `process.platform`

它被允许黑名单和白名单，虽然没有任何充分的理由这样做。

## CPU § ##

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

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

与`os`选项一样，您也可以将架构列入黑名单：

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

主机架构由确定 `process.arch`

## preferGlobal § ##

**弃用**

此选项用于触发npm警告，但不会再发出警告。纯粹出于信息目的。现在建议您尽可能将任何二进制文件安装为本地devDependencies。

## 私人§ ##

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

这是一种防止意外发布私有存储库的方法。如果您希望确保仅将某个包发布到特定注册表（例如，内部注册表），请使用`publishConfig`下面描述的 字典`registry`在发布时覆盖配置参数。

## publishConfig § ##

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

可以覆盖任何配置值，但只有“tag”，“registry”和“access”可能对于发布而言很重要。

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

## 默认值§ ##

npm将根据包内容默认一些值。

* `"scripts": {"start": "node server.js"}`
 
 如果<code class="highlighter-rouge">server.js</code>包的根目录中有文件，则npm将默认<code class="highlighter-rouge">start</code>命令<code class="highlighter-rouge">node server.js</code>。

* `"scripts":{"install": "node-gyp rebuild"}`
 
 如果<code class="highlighter-rouge">binding.gyp</code>包的根目录中有文件而您尚未定义<code class="highlighter-rouge">install</code>或<code class="highlighter-rouge">preinstall</code>脚本，则npm将默认<code class="highlighter-rouge">install</code>使用node-gyp进行编译。
 * `"contributors": [...]`
 
 如果<code class="highlighter-rouge">AUTHORS</code>包的根目录中有文件，则npm会将每一行视为一种<code class="highlighter-rouge">Name <email> (url)</code>格式，其中email和url是可选的。以a <code class="highlighter-rouge">#</code>或空白开头的行将被忽略。
 * ## 另见§ ##
 
 * semver
 * NPM-INIT
 * NPM-版本
 * NPM-配置
 * NPM-配置
 * NPM-帮助
 * NPM-安装
 * NPM-发布
 * NPM-卸载

[https_www.npmjs.com]: https://www.npmjs.com/
[node-semver]: https://github.com/isaacs/node-semver
[SPDX_ID]: https://spdx.org/licenses/
[OSI]: https://opensource.org/licenses/alphabetical
[SPDX_2.0]: https://www.npmjs.com/package/spdx
[Packages]: http://wiki.commonjs.org/wiki/Packages/1.0
[npm_package.json]: https://registry.npmjs.org/npm/latest
[semver]: https://semver.org/