npm-package.json Specifics of npm's package.json handling

DESCRIPTION

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

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

name

如果您打算发布软件包,则package.json中重要的是名称和版本字段,因为它们是必填字段. 名称和版本共同构成一个标识符,该标识符被假定为完全唯一. 对软件包的更改应与版本的更改同时进行. 如果您不打算发布您的软件包,则名称和版本字段是可选的.

名字就是你的名字.

一些规则:

一些技巧:

名称可以可选地以范围为前缀,例如@myorg/mypackage . 有关更多详细信息,请参见npm-scope .

version

If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version. If you don’t plan to publish your package, the name and version fields are optional.

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

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

description

在其中添加描述. 这是一个字符串. 如npm search列出的,这可以帮助人们发现您的包裹.

keywords

放入关键字. 它是一个字符串数组. 这可以帮助人们发现npm search列出的您的包裹.

homepage

项目首页的网址.

Example:

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

bugs

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

它看起来应该像这样:

{ "url" : "https://github.com/owner/project/issues"
, "email" : "[email protected]"
}

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

如果提供了网址,则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

The “author” is one person. “contributors” is an array of people. A “person” is an object with a “name” field and optionally “url” and “email”, like this:

{ "name" : "Barney Rubble"
, "email" : "[email protected]"
, "url" : "http://barnyrubble.tumblr.com/"
}

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

"Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)"

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

npm还会为您的npm用户信息设置一个顶级" maintainers"字段.

files

可选files字段是文件模式的数组,描述了将软件包作为依赖项安装时要包括的条目. 文件模式遵循与.gitignore类似的语法,但相反:包括文件,目录或全局模式( ***/*等)将使文件模式成为打包文件时包含在tarball中. 省略该字段将使其默认为["*"] ,这意味着它将包括所有文件.

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

您还可以在包的根目录或子目录中提供.npmignore文件,以防止文件被包含. 在程序包的根目录下,它不会覆盖"文件"字段,但在子目录中,它将覆盖. .npmignore文件的工作原理与.gitignore . 如果存在.gitignore文件,并且缺少.npmignore.npmignore .gitignore的内容.

文件包含了"的package.json#文件"栏中不能通过排除.npmignore.gitignore .

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

READMECHANGESLICENSENOTICE可以有任何大小写和扩展名.

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

main

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

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

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

browser

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

bin

许多软件包都有一个或多个要安装到PATH中的可执行文件. npm使此操作非常容易(实际上,它使用此功能来安装" npm"可执行文件.)

要使用此功能,请在package.json中提供一个bin字段,该字段是命令名到本地文件名的映射. 在安装时,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开头# ! /usr/ bin / env node # ! /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

如果您在directories.bin指定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" } }

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

有关软件包配置的更多信息,请参见npm-confignpm-scripts .

dependencies

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

请不要在您的dependencies对象中放置测试工具或编译器. 请参阅下面的devDependencies .

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

例如,这些都是有效的:

{ "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代替版本范围.

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

Git URLs as Dependencies

Git网址的格式为:

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

<protocol>gitgit+sshgit+httpgit+httpsgit+file .

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

Examples:

git+ssh://[email protected]:npm/cli.git#v1.0.27
git+ssh://[email protected]:npm/cli#semver:^5.0
git+https://[email protected]/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

As of version 2.0.0 you can provide a path to a local directory that contains a package. Local paths can be saved using npm install -S or npm install --save, using any of these forms:

../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.

For example:

{ "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对此主机进行require . 通常将其称为插件 . 值得注意的是,您的模块可能正在公开主机文档预期和指定的特定接口.

例如:

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

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

注意:如果npm版本1和2没有在依赖关系树中显式依赖更高版本,它们将自动安装peerDependencies . 在npm的下一个主要版本中( [电子邮件保护] ),情况将不再如此. 您将收到一条警告,提示您未安装peerDependency. npms 1和2中的行为经常令人困惑,很容易使您陷入依赖地狱,npm旨在尽可能避免这种情况.

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

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

bundledDependencies

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

如果您需要在本地保留npm软件包或通过单个文件下载将其提供,则可以通过在bundledDependencies数组中指定软件包名称并执行npm pack ,将软件包捆绑在tarball文件中.

例如:

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

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

我们可以通过运行npm pack获得awesome-web-framework-1.0.0.tgz文件. 该文件包含renderized的依赖renderizedsuper-streams ,可以通过执行npm install awesome-web-framework-1.0.0.tgz将其安装在新项目中. 请注意,软件包名称不包含任何版本,因为该信息是在dependencies指定的.

如果将其拼写为"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()
}

Entries in optionalDependencies will override entries of the same name in dependencies, so it’s usually best to only put in one place.

engines

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

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

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

如果指定"引擎"字段,则npm将要求"节点"在该列表中的某个位置. 如果省略了" engines",那么npm只会假设它可以在节点上运行.

您还可以使用"引擎"字段来指定哪些版本的npm能够正确安装程序. 例如:

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

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

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

DEPRECATED

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

private

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

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

publishConfig

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

可以覆盖任何配置值,但是对于发布而言,仅" tag"," registry"和" access"可能很重要.

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

DEFAULT VALUES

npm将根据软件包内容默认一些值.

SEE ALSO


by  ICOPY.SITE