npm package.json

描述

此文档是您需要了解的有关 package.json 文件中所需内容的全部信息。它必须是实际的 JSON，而不仅仅是 JavaScript 对象文字。本文档中描述的许多行为受中描述的配置设置的影响config。

姓名如果您计划发布您的包，您的 package.json 中最重要的内容是名称和版本字段，因为它们是必需的。名称和版本共同构成一个标识符，假定该标识符是完全唯一的。对包的更改应该伴随着对版本的更改。如果您不打算发布包，则名称和版本字段是可选的。名字就是你的东西叫什么。一些规则：名称必须小于或等于 214 个字符。这包括范围包的范围。作用域包的名称可以以点或下划线开头。这在没有范围的情况下是不允许的。新包的名称中不得包含大写字母。该名称最终成为 URL 的一部分、命令行上的参数和文件夹名称。因此，名称不能包含任何非 URL 安全字符。一些技巧：不要使用与核心节点模块相同的名称。不要在名称中加入“js”或“node”。假设它是 js，因为您正在编写 package.json 文件，并且您可以使用“engines”字段指定引擎。（见下文。）该名称可能会作为参数传递给 require()，因此它应该是简短的，但也应该具有合理的描述性。您可能需要检查 npm 注册表以查看是否已经存在使用该名称的内容，以免过于依赖它。 https://www.npmjs.com/名称可以选择性地以范围为前缀，例如`@myorg/mypackage. 请参阅 scope`了解更多详情。

版本如果您计划发布您的包，您的 package.json 中最重要的内容是名称和版本字段，因为它们是必需的。名称和版本共同构成一个标识符，假定该标识符是完全唯一的。对包的更改应该伴随着对版本的更改。如果您不打算发布包，则名称和版本字段是可选的。版本必须可由node-semver解析，它作为依赖项与 npm 捆绑在一起。（npm install semver自己使用。）

描述把描述放在里面。这是一个字符串。这有助于人们发现您的包裹，如中所列npm search。

关键词把关键字放进去。它是一个字符串数组。这有助于人们发现您的包裹，因为它在中列出npm search。

主页项目主页的 url。例子：

“主页” ：“https://github.com/owner/project#readme”

错误项目问题跟踪器的 url 和/或应报告问题的电子邮件地址。这些对于遇到包裹问题的人很有帮助。它应该是这样的：

{ "url" : "https://github.com/owner/project/issues" ,
“电子邮件” ：“project@hostname.com”
}

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

执照你应该为你的包指定一个许可证，以便人们知道他们如何被允许使用它，以及你对它施加的任何限制。如果您使用的是 BSD-2-Clause 或 MIT 等通用许可证，请为您使用的许可证添加当前的 SPDX 许可证标识符，如下所示：

{ “许可证” ：“BSD-3-条款”
}

您可以查看SPDX 许可证 ID 的完整列表。理想情况下，您应该选择 OSI批准的一种。如果您的软件包在多个通用许可下获得许可，请使用SPDX 许可表达式语法版本 2.0 string，如下所示：

{ “许可证” ：“（ISC 或 GPL-3.0）”
}

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

{ "license" : "在 <文件名> 中查看许可证"
}

然后包含一个<filename>在包的顶层命名的文件。一些旧包使用许可证对象或包含许可证对象数组的“许可证”属性：

// 无效的元数据 { “许可证” ：{
"类型" : "ISC" ,
"url" : "https://opensource.org/licenses/ISC"
} }

// 无效的元数据 { “许可证” ：[
{ “类型” ：“麻省理工学院” ， "url" : "https://www.opensource.org/licenses/mit-license.php" } , { "type" : "Apache-2.0" , "url" : "https://opensource.org/licenses/apache2.0.php" } ] }

这些样式现在已弃用。相反，使用 SPDX 表达式，如下所示：

{ “许可证” ：“ISC” }

{ “许可证” ：“（MIT 或 Apache-2.0）” }

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

{ “许可证” ：“未经许可” }

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

人员字段：作者、贡献者 “作者”是一个人。“贡献者”是一群人。“person”是一个带有“name”字段和可选的“url”和“email”的对象，像这样：

{ "name" : "Barney Rubble" ,
"email" : "b@rubble.com" ,
“网址” ：“http://barnyrubble.tumblr.com/”
}

或者，您可以将其全部缩短为一个字符串，然后 npm 将为您解析它：

{ “作者” ：“巴尼瓦砾 <b@rubble.com> (http://barnyrubble.tumblr.com/)” }

email 和 url 都是可选的。 npm 还使用您的 npm 用户信息设置顶级“维护者”字段。

资金您可以指定一个包含 URL 的对象，该 URL 提供有关帮助资助包开发的方法的最新信息，或字符串 URL 或以下内容的数组：

{ “资金” ：{ "类型" : "个人" ,
“网址” ：“http://example.com/donate”
} ,

“资金” ：{ "type" : "patreon" ,
“网址” ：“https://www.patreon.com/my-account”
} ,

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

“资金” ：[ { "类型" : "个人" ,
“网址” ：“http://example.com/donate”
} , "http://example.com/donateAlso" , { "type" : "patreon" ,
“网址” ：“https://www.patreon.com/my-account”
} ] }

用户可以使用npm fund子命令列出funding其项目的所有依赖项的URL，直接和间接。提供项目名称时还提供访问每个资助网址的快捷方式，例如：（ npm fund <projectname>当有多个网址时，将访问第一个）

档案可选files字段是一个文件模式数组，它描述了当您的包作为依赖项安装时要包含的条目。文件模式遵循与类似的语法.gitignore，但相反：包含文件、目录或 glob 模式（*,**/*等）将使该文件在打包时包含在 tarball 中。省略该字段将使其默认为["*"]，这意味着它将包含所有文件。一些特殊的文件和目录也会被包含或排除，无论它们是否存在于files数组中（见下文）。您还可以.npmignore在包的根目录或子目录中提供一个文件，以防止文件被包含在内。在包的根目录中，它不会覆盖“文件”字段，但在子目录中会覆盖。该.npmignore文件就像一个.gitignore. 如果有一个.gitignore文件并且.npmignore丢失了，.gitignore则将使用的内容。文件包含了“的package.json＃文件”栏中无法通过排除.npmignore或.gitignore。无论设置如何，始终包含某些文件： package.json``README``LICENSE / LICENCE“主要”字段中的文件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")，那么您的主模块的导出对象将被返回。这应该是相对于包文件夹根目录的模块。对于大多数模块来说，拥有一个主脚本是最有意义的，通常没有太多其他的东西。如果main未设置，则默认index.js位于包根文件夹中。

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

垃圾桶很多包都有一个或多个他们想要安装到 PATH 中的可执行文件。npm 使这变得非常简单（实际上，它使用此功能来安装“npm”可执行文件。）要使用它，请bin在 package.json 中提供一个字段，它是命令名到本地文件名的映射。当这个包被全局安装时，该文件将被链接到全局 bin 所在的位置，因此它可以按名称运行。当此包作为另一个包中的依赖项安装时，该文件将链接到该包可直接通过npm exec或通过其他脚本中的名称通过npm run-script. 例如，myapp 可能有这个：

{ “斌” ：{ “我的应用程序” ：“./cli.js” } }

因此，当您安装 myapp 时，它会创建一个从cli.js脚本到/usr/local/bin/myapp. 如果您有一个可执行文件，并且它的名称应该是包的名称，那么您可以将其作为字符串提供。例如：

{ "name" : "我的程序" , “版本” ：“1.2.5” ， "bin" : "./path/to/program" }

将与此相同：

{ "name" : "我的程序" , “版本” ：“1.2.5” ， “斌” ：{ “我的程序” ：“./path/to/program” } }

请确保中引用的文件以bin开头 #!/usr/bin/env node，否则脚本将在没有节点可执行文件的情况下启动！请注意，您还可以使用directory.bin设置可执行文件。有关可执行文件的更多信息，请参见文件夹。

男人指定单个文件或文件名数组以供man程序查找。如果只提供了一个文件，那么它会被安装为来自的结果man <pkgname>，而不管其实际文件名如何。例如：

{ "name" : "foo" , “版本” ：“1.2.3” ， "description" : "用于 fooing foos 的打包 foo fooer" , "main" : "foo.js" , “人” ：“./ man / doc.1” }

将链接./man/doc.1文件，使其成为目标man foo 如果文件名不以包名开头，则它是前缀。所以这：

{ "name" : "foo" , “版本” ：“1.2.3” ， "description" : "用于 fooing foos 的打包 foo fooer" , "main" : "foo.js" , “男人” ：[ "./man/foo.1" , “./man/bar.1” ] }

将创建文件来做man foo和man foo-bar。 man 文件必须以数字结尾，.gz如果它们被压缩，则可以选择后缀。该数字指示文件安装到哪个 man 部分。

{ "name" : "foo" , “版本” ：“1.2.3” ， "description" : "用于 fooing foos 的打包 foo fooer" , "main" : "foo.js" , “男人” ：[ "./man/foo.1" , “./man/foo.2” ] }

将创建条目man foo和man 2 foo

目录 CommonJS Packages规范详细说明了一些可以使用directories对象指示包结构的方法。如果您查看npm 的 package.json，您会看到它包含 doc、lib 和 man 目录。将来，这些信息可能会以其他创造性的方式使用。

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

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

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

{ “存储库” ：{ "类型" : "git" , "url" : "https://github.com/npm/cli.git" } }

URL 应该是一个公开可用的（可能是只读的）url，可以直接传递给 VCS 程序，无需任何修改。它不应该是您放入浏览器的 html 项目页面的 url。是给电脑用的。对于 GitHub、GitHub gist、Bitbucket 或 GitLab 存储库，您可以使用与相同的快捷语法npm install：

{ "repository" : "npm/npm" ,

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

“存储库” ：“要点：11081aaa281” ，

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

“存储库” ：“gitlab：用户/仓库” }

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

{ “存储库” ：{ "类型" : "git" , "url" : "https://github.com/facebook/react.git" , “目录” ：“包/react-dom” } }

脚本 “scripts”属性是一个字典，其中包含在包生命周期中的不同时间运行的脚本命令。键是生命周期事件，值是在该点运行的命令。请参阅scripts以了解有关编写包脚本的更多信息。

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

{ "name" : "foo" , “配置” ：{ “端口” ：“8080” } }

它也可以有一个引用npm_package_config_port环境变量的“启动”命令。

依赖依赖项在一个简单的对象中指定，该对象将包名称映射到版本范围。版本范围是一个字符串，它具有一个或多个以空格分隔的描述符。依赖项也可以用 tarball 或 git URL 来标识。请不要在您的dependencies对象中放置测试工具或转译器或其他“开发”时间工具。见devDependencies，下面。有关指定版本范围的更多详细信息，请参阅semver。 version必须version完全匹配>version 必须大于 version``>=version 等等<version``<=version``~version“大约相当于版本”见 semver^version“兼容版本”见semver1.2.x 1.2.0、1.2.1 等，但不是 1.3.0http://... 请参阅下面的“作为依赖项的 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请参阅下面的本地路径例如，这些都是有效的：

{ “依赖关系” ：{ "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" , "小精灵" : "~1.2.3" , "二" : "2.x" , "thr" : "3.3.x" , "lat" : "最新的" , "dyl" : "文件：../dyl" } }

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

Git URL 作为依赖项 Git 网址的格式为：

<协议> ：// [ <用户> [ ：<密码> ] @ ] <主机名> [ ：<端口> ] [ ：] [ / ] <路径> [ #<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 网址称为“foo”：“user/foo-project”。就像 git URL 一样，commit-ish可以包含后缀。例如：

{ "name" : "foo" , “版本” ：“0.0.0” ， “依赖关系” ：{ "express" : "expressjs/express" , "mocha" : "mochajs/mocha#4727d357ea" , “模块” ：“用户/repo#feature\/branch” } }

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

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

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

{ "name" : "baz" , “依赖关系” ：{ “bar” ：“文件：../foo/bar” } }

此功能有助于本地离线开发和创建需要在不想访问外部服务器的地方安装 npm 的测试，但不应在将包发布到公共注册表时使用。

开发依赖如果有人计划在他们的程序中下载和使用您的模块，那么他们可能不想或不需要下载和构建您使用的外部测试或文档框架。在这种情况下，最好将这些附加项目映射到一个 devDependencies对象中。这些东西将在执行时npm link或npm install从包的根目录安装，并且可以像任何其他 npm 配置参数一样进行管理。有关config该主题的更多信息，请参阅。对于非特定于平台的构建步骤，例如将 CoffeeScript 或其他语言编译为 JavaScript，请使用prepare脚本执行此操作，并使所需的包成为 devDependency。例如：

{ "name" : "ethopia-waza" , “描述” ：“令人愉悦的果味咖啡品种” ， “版本” ：“1.2.3” ， “开发依赖” ：{ “咖啡脚本” ：“~1.6.3” } , “脚本” ：{ “准备” ：“咖啡-o lib/-c src/waza.coffee” } , "main" : "lib/waza.js" }

该prepare脚本将在发布之前运行，以便用户无需自行编译即可使用该功能。在开发模式下（即本地运行npm install），它也会运行这个脚本，以便您可以轻松测试它。

对等依赖在某些情况下，您希望表达您的包与主机工具或库的兼容性，而不必执行require此主机的操作。这通常称为插件。值得注意的是，您的模块可能会公开主机文档所预期和指定的特定接口。例如：

{ "name" : "拿铁茶" , “版本” ：“1.3.5” ， “peerDependencies” ：{ “茶” ：“2.x” } }

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

├── 拿铁茶@1.3.5 └── 茶@2.2.0

在 npm 版本 3 到 6 中，peerDependencies不会自动安装，如果在树中发现对等依赖项的无效版本，则会发出警告。由于NPM V7的，peerDependencies被默认安装。如果无法正确解析树，尝试安装具有冲突要求的另一个插件可能会导致错误。因此，请确保您的插件要求尽可能广泛，而不是将其锁定为特定的补丁版本。假设主机符合semver，只有主机包的主要版本中的更改才会破坏您的插件。因此，如果您使用过主机包的每个 1.x 版本，请使用"^1.0"或"1.x" 来表达这一点。如果您依赖 1.5.2 中引入的功能，请使用 "^1.5.2".

对等依赖元当用户安装您的软件包时，如果中指定的软件包peerDependencies尚未安装，npm 将发出警告。该 peerDependenciesMeta字段用于为 npm 提供有关如何使用对等依赖项的更多信息。具体来说，它允许对等依赖项标记为可选。例如：

{ "name" : "拿铁茶" , “版本” ：“1.3.5” ， “peerDependencies” ：{ "茶" : "2.x" , “豆浆” ：“1.2” } , “peerDependenciesMeta” ：{ “豆浆” ：{ “可选” ：真 } } }

将对等依赖项标记为可选可确保soy-milk在主机上未安装软件包时npm 不会发出警告。这允许您集成各种主机包并与之交互，而无需安装所有主机包。

捆绑依赖这定义了在发布包时将捆绑的包名称数组。如果您需要在本地保留 npm 包或通过单个文件下载使它们可用，您可以通过在bundledDependencies 数组中指定包名称并执行npm pack. 例如：如果我们像这样定义 package.json：

{ "name" : "awesome-web-framework" , “版本” ：“1.0.0” ， “捆绑依赖” ：[ “渲染” ， “超级流” ] }

我们可以awesome-web-framework-1.0.0.tgz通过运行获取文件npm pack。此文件包含的依赖关系renderized，并super-streams可以通过执行安装在一个新的项目npm install awesome-web-framework-1.0.0.tgz。请注意，包名称不包含任何版本，因为该信息在dependencies. 如果这是拼写"bundleDependencies"，那么这也很荣幸。

可选依赖项如果可以使用依赖项，但如果找不到或安装失败，您希望 npm 继续，那么您可以将其放入 optionalDependencies对象中。这是包名称到版本或 url 的映射，就像dependencies对象一样。不同之处在于构建失败不会导致安装失败。运行npm install --no-optional将阻止安装这些依赖项。处理缺少依赖项仍然是您的程序的责任。例如，这样的事情：

试试{ var foo =要求（'foo' ） var fooVersion = require ( 'foo/package.json' ) 。版本 }赶上（呃）{
foo =空 } 如果( notGoodFooVersion ( fooVersion ) ) {
foo =空 }

// .. 然后在你的程序中..

如果（富）{
富。doFooThings ( ) }

中的条目optionalDependencies将覆盖中的同名条目 dependencies，因此通常最好只放在一个地方。

引擎您可以指定您的东西适用的节点版本：

{ “引擎” ：{ “节点” ：“>=0.10.3 <15” } }

而且，与依赖项一样，如果您不指定版本（或者如果您指定“ * ”作为版本），那么任何版本的节点都可以。您还可以使用“引擎”字段来指定哪些版本的 npm 能够正确安装您的程序。例如：

{ “引擎” ：{ “npm” ：“~1.0.20” } }

除非用户设置了engine-strictconfig 标志，否则这个字段只是建议性的，只有当你的包作为依赖项安装时才会产生警告。

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

{ “操作系统” ：[ “达尔文” ， “Linux” ] }

您还可以阻止而不是允许操作系统，只需在被阻止的操作系统前面加上一个“！”：

{ “操作系统” ：[ “！win32” ] }

主机操作系统由 process.platform 允许阻止和允许一个项目，尽管没有任何充分的理由这样做。

中央处理器如果您的代码仅在某些 CPU 架构上运行，您可以指定哪些架构。

{ “CPU” ：[ "x64" , “ia32” ] }

与该os选项一样，您还可以阻止架构：

{ “CPU” ：[ "!arm" , “！mips” ] }

主机架构由 process.arch

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

发布配置这是一组将在发布时使用的配置值。如果您想设置标记、注册表或访问权限，这将特别方便，这样您就可以确保给定的包没有被标记为“最新”、未发布到全局公共注册表或默认情况下范围模块是私有的。查看config可覆盖的配置选项列表。

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

{ "name" : "工作区示例" , “工作区” ：[ “./包/*” ] }

有关workspaces更多示例，请参见。

默认值 npm 将根据包内容默认一些值。 "scripts": {"start": "node server.js"} 如果server.js包的根目录中有一个文件，那么 npm 会将start命令默认为node server.js. "scripts":{"install": "node-gyp rebuild"} 如果binding.gyp你的包根目录中有一个文件并且你没有定义install或preinstall脚本，npm 将默认 install使用 node-gyp 编译命令。 "contributors": [...] 如果AUTHORS包的根目录中有一个文件，npm 会将每一行视为一种Name <email> (url)格式，其中 email 和 url 是可选的。以 a#或开头的空白行将被忽略。