阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

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