package.json for NPM 文件详解

package.json 文件描述了一个 NPM 包的所有相关信息,包括作者、简介、包依赖、构建等信息。格式必须是严格的 JSON 格式。

通常我们在创建一个 NPM 程序时,可以使用 npm init 命令,通过交互式的命令,自动生成一个 package.json 文件,里面包含了常用的一些字段信息,但远不止这么简单。通过完善 package.json 文件,我们可以让 npm 命令更好地为我们服务。

name

nameversion 是 package.json 中最重要的两个字段,也是发布到 NPM 平台上的唯一标识,如果没有正确设置这两个字段,包就不能发布和被下载。

下面是官方给出的一些建议:

  • 名字里不要再包含”js” 和”node”,因为默认 NPM 包就是 node.js 程序,不过你可以通过 engines 字段来指定。
  • 名字将会被作为 url 的一部分,所有要符合 http url 的一般命名规则,不能包含 url 非法字符,也不能以 ._ 开头。
  • 名字也将作为 require() 命令的参数,所以应该尽量简明。
  • 如果包要发布到 NPM 平台上的话,最好先检查下有没有重名, 并且字母只能全部小写。

新版本的 NPM 可以指定 scope, 名字可以加前缀标识,如 @ijse/mypackage

version

这个字段的取值需要符合 node-semver 的规则,详细可以见其文档。

description

包的描述信息,将会在 npm search 的返回结果中显示,以帮助用户选择合适的包。

keywords

包的关键词信息,是一个字符串数组,同上也将显示在 npm search 的结果中。

homepage

包的主页地址

bugs

包的 bug 跟踪主页地址,应该如下设置:

license

包的开源协议名称

author

包的作者,可以是字符串或对象:

或者:

contributors, maintainers

包的贡献者,是一个数组。

files

包所包含的所有文件,可以取值为文件夹。

通常我们还是用 .npmignore 来去除不想包含到包里的文件。

main

包的入口文件,如 index.js

bin

如果你的包里包含可执行文件,通过设置这个字段可以将它们包含到系统的 PATH 中,这样直接就可以运行,很方便。如:

当包被安装后,NPM 将创建一个 cli.js 文件的链接到 /usr/local/bin/iapp 下。

man

为系统的 man 命令提供帮助文档, 如:

帮助文件的文件名必须以 数字 结尾,如果是压缩的,需要以 .gz 结尾。

如果是字符串数组:

则分别可以 man foo, man foo-bar, man 2 foo 来查看。

directories

CommonJS 包所要求的目录结构信息,目前除了告诉别人你的程序目录结构,貌似没有别的什么用。
下级字段可以是:lib, bin, man, doc, example。
每个都是字符串

repository

包的仓库地址。如:

scripts

通过设置这个可以使 NPM 调用一些命令脚本,封装一些功能。

config

添加一些设置,可以供 scripts 读取用,同时这里的值也会被添加到系统的环境变量中。

npm start 的时候会读取到 npm_package_config_port 环境变量。

同时也可以使用 npm config 命令来修改设置:

dependencies

指定依赖的其它包,这些依赖是指包发布后正常执行时所需要的,如果是开发中依赖的包,可以在 devDependencies 设置。

通常使用下面命令来安装:

形式可以有如下多种:

  • version 严格匹配某个版本
  • >version 必须大于某个版本
  • >=version
  • <version
  • <=version
  • ~version 大概匹配某个版本
  • ^version 兼容某个版本
  • 1.2.x 可以是 1.2.0, 1.2.1 等等,但不能是 1.3.0
  • http://... 指定 tarball 的 url 地址
  • * 任何版本都可以
  • "" 同上
  • version1 - version2 >=version1 <=version2
  • range1 || range2 满足 range1 或 range2
  • git://... git 地址
  • user/repo 同上
  • tag 指定某个 tag 的版本
  • path/path 本地包所有文件夹

下面都是可以用的:

Git URL 可以有如下种形式:

devDependencies

这些依赖只有在开发时候才需要。

peerDependencies

相关的依赖,如果你的包是插件,而用户在使用你的包时候,通常也会需要这些依赖(插件),那么可以将依赖列到这里。

举个例子,如 karma, 它的 package.json 中有设置:

这些都是 karma 的相关插件,一般使用 karma 的时候都会需要。

bundledDependencies

绑定的依赖包,发布的时候这些绑定包也会被一同发布。

optionalDependencies

即使这些依赖没有,也可以正常安装使用

engines

指定包运行的环境

engineStrict

设置为 true 强制限定 engine

os

指定你的包可以在哪些系统平台下运行。

即可以在 darwinlinux 平台下运行,而不能在 win32 下。这里设定的取值是来自 process.platform 的。

cpu

可以指定包运行的 cpu 架构,如

取值来自 process.arch

preferGlobal

如果你的包是命令行运行的,那可以将其设置为 true 建议用户全局 (npm install -g) 安装。但它并不强制用户。

private

设为 true 这个包将不会发布到 NPM 平台下。

publishConfig

这个字段用于设置发布时候的一些设定。尤其方便你希望发布前设定指定的 tagregistry

也可以设定其它子字段,但只有 tagregistry 会影响到发布。

NPM 的一些默认值说明

  • "scripts": { "start": "node server.js" }
    如果在项目根目录下含有 server.js 文件,则 NPM 会自动设置此值。
  • "scripts": { "preinstall": "node-gyp rebuild" }
    如果在项目根目录下含有 binding.gyp 文件,则 NPM 会自动设置此值。
  • "contributors": [...]
    如果项目根目录下含有 AUTHORS 文件,则 NPM 会自动将每一行以 Name <i@ijser.cn> (url) 的格式读取并设定此字段。

发表评论