npm version 7.x

Description

这个文档就是您所需要知道的关于您的包中需要什么内容的全部信息。json 文件。它必须是实际的 JSON，而不仅仅是 JavaScript 对象文字。

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

name

如果您计划发布您的包，那么包中最重要的东西。Json 是需要的名称和版本字段。名称和版本一起构成一个标识符，该标识符被认为是完全惟一的。对包的更改应该与对版本的更改同时进行。如果不打算发布包，那么名称和版本字段是可选的。

名字就是你的东西的名字。

制定一些规则

• 名称必须小于等于 214 个字符。这包括作用域包的作用域。
• 作用域包的名称可以以点或下划线开头。没有作用域，这是不允许的。
• 新包的名称中不能有大写字母。
• 该名称最终成为 URL、命令行参数和文件夹名称的一部分。因此，名称不能包含任何非 url 安全字符。

注意事项

• 不要使用与核心 Node 模块相同的名称。
• 不要在名称中添加“js”或“node”。假设它是 js，因为你正在写一个包。Json 文件，您可以使用“引擎”字段指定引擎。(见下文)。
• 名称可能会作为参数传递给 require()，所以它应该是简短的，但也要有合理的描述性。
• 你可能想要检查 npm 注册表，看看是否已经有这个名字的东西，在你太依赖它之前。https://www.npmjs.com/

名称可以有选择地使用作用域作为前缀，例如：@myorg/mypackage。更多细节请参见scope。

version

如果您计划发布您的包，那么包中最重要的东西。Json 是需要的名称和版本字段。名称和版本一起构成一个标识符，该标识符被认为是完全惟一的。对包的更改应该与对版本的更改同时进行。如果不打算发布包，那么名称和版本字段是可选的。

Version 必须能被 node-semver 解析，它被 npm 捆绑为一个依赖项。(npm install semver to use it yourself.)

description

写一段描述。它是一个字符串。这有助于人们发现你的包，可以使用 npm search 搜索到

keywords

写上关键词。它是一个字符串数组。这有助于人们发现你的包，可以使用 npm search 搜索到

homepage

项目主页的 url。

例如：

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

bugs

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

它应该是这样的:

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

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

如果提供了一个 url，它将被 npm bug 命令使用。

license

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

如果您使用的是通用许可证，如 BSD-2-Clause 或 MIT，为您正在使用的许可证添加一个当前 SPDX 许可证标识符，如下所示:

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

你可以在网上查 the full list of SPDX license IDs。理想情况下，你应该选择OSI认可的。

如果您的包使用多个通用许可证，使用 SPDX license expression syntax version 2.0 string，例如：

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

people fields: author, contributors

"author"代表一个人，"contributors"代表很多人，"person"是具备"name"字段的（"url"或者"emial"可选）的一个对象，例如：

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

或者你也可以把它缩短成一个字符串，npm 会为你解析它:

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

email 和 url 都是可选的。

NPM 还设置了一个包含 NPM 用户信息的顶级“maintainers”字段。

funding

你可以指定一个包含最新信息的 URL 的对象来帮助开发你的包，或者一个 URL 字符串，或者一个数组:

{
  "funding": {
    "type" : "individual",
    "url" : "http://example.com/donate"
  },

  "funding": {
    "type" : "patreon",
    "url" : "https://www.patreon.com/my-account"
  },

  "funding": "http://example.com/donate",

  "funding": [
    {
      "type" : "individual",
      "url" : "http://example.com/donate"
    },
    "http://example.com/donateAlso",
    {
      "type" : "patreon",
      "url" : "https://www.patreon.com/my-account"
    }
  ]
}

用户可以使用 npm fund 子命令来列出他们项目中所有直接或间接依赖的 funding url。当提供项目名称时，访问每个资助 url 的快捷方式也是可用的，例如: npm fund (当有多个 url 时，将访问第一个 url)

files

可选的 files 字段是一个文件模式数组，描述了当包作为依赖项安装时要包含的条目。文件模式遵循类似的语法 .gitignore，相反: 包含一个文件、目录或 glob 模式 ( *, */ , and such) 将使该文件在打包时包含在 tarball 中。

省略该字段将使其默认值为 [“*”] ，这意味着它将包括所有文件。

还包括或排除一些特殊文件和目录，无论它们是否存在于 file 数组中(见下文)。

你也可以在包的根目录或子目录中提供一个 .npmignore 文件，这样就不会包含文件了。在包的根目录下，它不会覆盖“files”字段，但在子目录下它会覆盖。.npmignore文件就像 .gitignore文件一样工作。如果有一个 .gitignore 文件，而缺少 .npmignore 文件，.gitignore的内容将被替换。

npm 包中包含的文件。 “package.json#files” 字段不能通过 .npmignore 或 .gitignore排除。

无论设置如何，某些文件总是包含在其中:

• package.json
• README
• LICENSE / LICENCE
• 包含 main 字段的文件

README & LICENSE 可以有任何情况和扩展。

相反，有些文件总是被忽略:

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._**
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json(想发布它使用npm-shrinkwrap.json)

main

主字段是一个模块 ID，它是程序的主要入口点。意思是如果你的包命名为 foo，并且有用户安装了它，然后使用 require(“foo”)，然后将返回主模块的 exports 对象。

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

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

如果 main 未设置，默认为 packages 根目录下的 index.js。

browser

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

bin

很多包都有一个或多个想要安装到 PATH 中的可执行文件。NPM 让这变得非常简单(事实上，它使用这个特性来安装“NPM”可执行文件)。

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。

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包规范详细说明了几种使用目录对象来指示包结构的方法。npm’s package.json 您将看到它包含 doc、lib 和 man 目录。

在未来，这些信息可能被用于其他创造性的方式。

directories.bin

如果您在directory .bin中指定了一个bin目录，那么将添加该文件夹中的所有文件。

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

directories.man

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

repository

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

照这样子去做：

{
  "repository": {
    "type": "git",
    "url": "https://github.com/npm/cli.git"
  }
}

URL 应该是一个公开的(可能是只读的)URL，可以直接传递给 VCS 程序，不需要任何修改。它不应该是您放在浏览器中的 html 项目页面的 url。这是电脑。

对于 GitHub、GitHub gist、Bitbucket 或 GitLab 仓库，你可以使用与安装 npm 相同的快捷语法npm install:

{
  "repository": "npm/npm",

  "repository": "github:user/repo",

  "repository": "gist:11081aaa281",

  "repository": "bitbucket:user/repo",

  "repository": "gitlab:user/repo"
}

scripts

"scripts"属性是一个字典，包含在包生命周期的不同时间运行的脚本命令。关键是生命周期事件，值是此时要运行的命令。

请参阅脚本以了解关于编写包脚本的更多信息。

config

一个“config”对象可以用来设置包脚本中使用的配置参数，这些脚本在升级过程中持久化。例如，如果一个包有以下内容:

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

它还可以有一个引用npm_package_config_port环境变量的“start”命令。

dependencies

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

请不要将测试工具、编译器或其他“开发”时工具放在依赖项对象中。参见下面的devDependencies。

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

• version Must match version exactly
• >version Must be greater than version
• >=version etc
• <version
• <=version
• ~version “Approximately equivalent to version” See semver
• ^version “Compatible with version” See semver
• 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
• http://… See ‘URLs as Dependencies’ below
• * Matches any version
• “” (just an empty string) Same as *
• version1 - version2 Same as >=version1 <=version2.
• range1 || range2 Passes if either range1 or range2 are satisfied.
• git… See ‘Git URLs as Dependencies’ below
• user/repo See ‘GitHub URLs’ below
• tag A specific version tagged and published as tag See npm dist-tag
• path/path/path See Local Paths - 本文档 local Paths below

例如，这些都是有效的:

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

您可以指定一个 tarball URL 来代替版本范围。
这个 tarball 将在安装时下载并安装到您的包中。

Git URLs as Dependencies

Git 的 url 是这样的:

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

是git, git+ssh, git+http, git+https，或者git+file中的一个。

如果提供了**#<commit-ish>，它将用于准确地克隆该提交。如果 commit-ish 的格式为#semver:<semver>，<semver>** 可以是任何有效的 semver 范围或确切的版本，npm 将在远程存储库中查找与该范围匹配的任何标签或 ref，就像查找注册表依赖项一样。如果没有指定 #<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 URLs

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

Local Paths

从 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 配置参数一样管理。有关该主题的更多信息，请参见配置。

对于不特定于平台的构建步骤，比如将 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脚本将在发布之前运行，这样用户就可以使用功能，而无需自己编译。在 dev 模式下(即本地运行npm install)，它也会运行这个脚本，这样你就可以轻松地测试它。

peerDependencies

在某些情况下，您希望表示您的包与主机工具或库的兼容性，而不一定需要执行此主机的要求。这通常被称为插件。值得注意的是，您的模块可能会暴露一个特定的接口，这是宿主文档所期望和指定的。
例如：

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

在 npm 版本 3 到 6 中，peerDependencies 不会自动安装，如果在树中发现 peer dependency 的无效版本，将会发出警告。从 npm v7 开始，默认安装了 peerDependencies。

试图安装另一个需求冲突的插件可能会导致错误，如果树不能正确解决。出于这个原因，确保你的插件需求尽可能广泛，而不是锁定在特定的补丁版本上。

假设主机遵循 semver，只有主机包的主版本的变化会破坏你的插件。因此，如果你处理过每一个 1。X 版本的主机包，使用 ^1.0或 1.X来表示。如果您依赖于 1.5.2 中引入的特性，请使用 ^1.5.2。

peerDependenciesMeta

当用户安装你的包时，如果在 peerDependencies 中指定的包还没有安装，npm 将发出警告。peerDependenciesMeta 字段为 npm 提供了更多关于如何使用对等依赖的信息。具体来说，它允许将对等依赖项标记为可选的。
例如:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x",
    "soy-milk": "1.2"
  },
  "peerDependenciesMeta": {
    "soy-milk": {
      "optional": true
    }
  }
}

将对等依赖标记为可选可以确保如果没有在主机上安装soy-milk包，npm 不会发出警告。这允许您与各种主机包集成并交互，而不需要安装所有的主机包。

bundledDependencies

它定义了一个包名数组，在发布包时将绑定该包。

当你需要在本地保存 npm 包或通过单个文件下载它们时，你可以通过在bundledDependencies数组中指定包名并执行npm pack来将这些包打包到 tarball 文件中。
例如:
如果我们定义一个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 继续，如果它找不到或安装失败，那么你可以把它放在optionalDependencies对象中。这是包名到版本或 url 的映射，就像依赖项对象一样。不同的是，构建失败不会导致安装失败。运行npm install --no-optional将阻止这些依赖被安装。

处理依赖项的缺乏仍然是程序的责任。例如，像这样:

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

你可以指定你的东西工作的节点的版本:

{
  "engines": {
    "node": ">=0.10.3 <15"
  }
}

而且，与依赖项一样，如果没有指定版本(或者指定“*”作为版本)，则可以使用任何版本的节点。
你也可以使用"engines"字段来指定哪个版本的 npm 能够正确安装你的程序。例如:

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

除非用户设置了 engine-strict 配置标志，否则此字段仅为建议字段，仅在包作为依赖项安装时产生警告。

os

你可以指定你的模块将运行在哪个操作系统上:

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

你也可以阻止而不是允许操作系统，只是在被阻止的 os 前加上一个’!'：

{
  "os": [
    "!win32"
  ]
}

主机操作系统由process.platform决定
它允许同时阻止和允许一个条目，尽管没有任何好的理由这样做。

cpu

如果您的代码只在特定的 cpu 架构上运行，那么您可以指定哪一种架构。

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

像os选项一样，你也可以阻塞架构:

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

主机架构由process.arch决定

private

如果你在 package.json 中设置了 “private”: true，那么 npm 将拒绝发布它。
这是一种防止意外发布私有存储库的方法。如果您希望确保给定的包只发布到特定的注册表(例如，内部注册表)，那么使用下面描述的publishConfig字典在发布时覆盖注册表配置参数。

publishConfig

这是一组将在发布时使用的配置值。如果您想设置标记、注册表或访问权限，那么它特别方便，这样您可以确保给定的包没有标记为“latest”，没有发布到全局公共注册表，或者有作用域的模块在默认情况下是私有的。
请参阅配置以查看可重写的配置选项列表。

workspaces

可选的workspaces字段是一个文件模式数组，描述了本地文件系统中的位置，安装客户端应该查找这些位置，以找到需要用符号链接到顶级node_modules文件夹的每个工作空间。
它可以描述作为工作区使用的文件夹的直接路径，也可以定义将解析到这些相同文件夹的 globs。
在下面的例子中，位于./packages 文件夹内的所有文件夹将被视为工作区，只要它们有有效的包。其中的 Json 文件:
更多参阅工作空间

DEFAULT VALUES

NPM 会根据包的内容默认一些值。

• “scripts”: {“start”: “node server.js”}

如果在你的包的根目录下有一个server.js文件，那么 npm 会默认将启动命令设置为node server.js。

• “scripts”:{“install”: “node-gyp rebuild”}

如果有binding.gyp文件在您的包的根目录下，并且您还没有定义安装或预安装脚本，npm将默认使用node-gyp编译安装命令。

• “contributors”: […]

如果在包的根目录下有一个AUTHORS文件，npm将把每一行作为**Name (url)**格式处理，其中email和url是可选的。以#开头或为空的行将被忽略。

SEE ALSO

• semver
• workspaces
• npm init
• npm version
• npm config
• npm help
• npm install
• npm publish
• npm uninstall