NPM package.json

🌙
手机阅读
本文目录结构

npm 的 package.json 记录了该包的具体表述;

说明

您需要了解所有关于 package.json 文件中所需内容的信息。它必须是实际的 JSON,而不仅仅是 JavaScript 对象文字。

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

name

如果您打算发布软件包,则 package.json 中最重要的是名称和版本字段,因为它们是必填字段。

名称和版本共同构成一个标识符,该标识符被假定为完全唯一。

对软件包的更改应与版本的更改同时进行。

如果您不打算发布您的软件包,则名称和版本字段是可选的。

name 就是你的名字。

一些规则:

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

一些技巧:

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

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

version

如果您打算发布软件包,则 package.json 中最重要的是"name"和"version"字段,因为它们是必填字段。

名称和版本共同构成一个标识符,该标识符被假定为完全唯一。

对软件包的更改应与版本的更改同时进行。

如果您不打算发布您的软件包,则名称和版本字段是可选的。

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

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

description

在其中添加描述。这是一个字符串。

如中所列,这可以帮助人们发现您的包 npm search

keywords

放入关键字。它是一个字符串数组。

这可以帮助人们发现您的软件包(如中所列)npm search。

homepage

项目首页的网址。

例:

"homepage": "https://github.com/anbang/ethereum-wallet-by-electron-vue#readme"

bugs

项目的问题跟踪器的 URL 和 / 或应向其报告问题的电子邮件地址。

这些对于遇到您的包问题的人很有帮助。

它看起来应该像这样:

{
  "url" : "https://github.com/anbang/ethereum-wallet-by-electron-vue/issues",
  "email" : "anbang@axihe.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 以防止意外发布。

people fields: author, contributors

“author” 是一个人。 “contributors"是一群人。 “person"是具有"name"字段以及(可选)“url” and “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 用户信息设置一个顶级 “maintainers” 字段。

files

可选 files 字段是文件模式的数组,描述了将软件包作为依赖项安装时要包括的条目。

文件格式遵循与相似的.gitignore语法;

但是相反:包括文件,目录或全局格式(*,\*\*/*等)将使文件格式在打包时包含在 tarball 中。

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

某些特殊文件和目录也被包括或排除在外,无论它们是否存在于 files 数组中(请参见下文)。

您还可以。npmignore 在包的根目录或子目录中提供文件,以防止文件被包含。

在程序包的根目录下,它不会覆盖“文件”字段,但在子目录中,它将覆盖。

该。npmignore 文件的工作方式就像 .gitignore。如果有。gitignore 文件但。npmignore 缺少文件,.gitignore 则将使用的内容。

无法通过.npmignore.gitignore排除 "package.json#files字段中包含的文件。

无论设置如何,总是会包含某些文件:

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

READMECHANGESLICENSENOTICE 可以有任何情况下和延伸。

相反,某些文件总是被忽略:

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

main

主要字段是模块 ID,它是程序的主要入口点。

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

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

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

browser

如果要在客户端使用您的模块,则应使用浏览器字段而不是主字段。

这有助于提示用户它可能依赖于 Node.js 模块中不可用的原语。(例如 window)

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

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 fooman 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 fooman 2 foo

directories

CommonJS Packages 规范详细介绍了几种使用 directories 对象指示软件包结构的方法。

如果查看 npm 的 package.json,

则会看到它具有 doc,lib 和 man 的目录。

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

directories.lib

告诉人们您的图书馆大部分在哪里。对于 lib 文件夹,没有任何特别的处理,但这是有用的元信息。

directories.bin

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

由于 bin 指令的工作方式,同时指定 bin 路径和设置 directories.bin 是错误的。

如果要指定单个文件,请使用 bin,对于现有 bin 目录中的所有文件,请使用 directories.bin。

directories.man

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

directories.doc

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

directories.example

在此处放入示例脚本。有一天,它可能会以某种巧妙的方式暴露出来。

directories.test

将您的测试放在这里。它目前尚未公开,但可能会在将来发布。

repository

指定代码所在的位置。这对想要贡献的人很有帮助。如果 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

“scripts"属性是一个字典,包含在包的生命周期中的各个时间运行的脚本命令。

关键是生命周期事件,值是在那一点运行的命令。

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

config

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

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

然后有一个"start"命令,该命令随后引用了 npm_package_config_port 环境变量,

那么用户可以通过这样做来覆盖它 npm config set foo:port 8001

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

dependencies

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

请不要在您的 dependencies 物体中放置测试线束或编译器 。 参见 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 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"
  }
}

URL 作为依赖项

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

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

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 URL

从 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 -Snpm install --save 使用以下任意形式保存本地路径:

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

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

例如:

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

此功能对于本地脱机开发和创建需要 npm 安装的测试很有用,您不想在不打外部服务器的地方安装 npm,

但是在将程序包发布到公共注册表时不应使用。

devDependencies

如果有人计划在其程序中下载和使用您的模块,则他们可能不想或不需要下载并构建您使用的外部测试或文档框架。

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

这些东西将在安装时 npm linknpm 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

请注意,软件包名称不包含任何版本,因为该信息在中指定 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

您可以指定您的东西可以使用的节点版本:

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

并且,与依赖项一样,如果您不指定版本(或如果指定"*"作为版本),则任何版本的节点都可以。

如果指定 “engines” 字段,

则 npm 将要求 “node” 在该列表中的某个位置。

如果省略了 “engines” ,那么 npm 只会假设它可以在节点上运行。

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

例如:

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

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

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

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

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

publishConfig

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

可以覆盖任何配置值,但是对于发布而言,仅 “tag”, “registry” and “access” 可能很重要。

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

默认值

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 #或空白开头的行将被忽略。

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

目前重心已经放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>