package.json里的一些属性讲解

内容来自 npm官方文档 , 本文做中文解释.

name, version

首先, 包名字是必须的. 版本号也是必须的.

npm规定了, 一个package是由名字加版本号作为唯一标识的.

比如 express@4.2.0 , koa@2.1.1 , 不同的包名或者版本号, 对应的内容是不一样的.

以上内容比较好理解, 接下来我补充几点:

• 包名必须少于等于 214 字符,
• 包名不能以 .或_开头
• 包名不能含有大写字母 (历史原因, 有的老包还有大写字母,新的已经不能用大写字母)
• 另外, 一些URL规范里不允许的字符也不能用(具体哪些字符就需要大家自己查查了)
• 建议不要在包名里包含js`node`等字眼, 因为npm默认就是js或node的
• 因为包名最终会用在require语句里, 所以尽可能短一些,但要注意能明确表达自己的用途
• 你开发一个包之前, 最好自己上 npm官网看看名字是不是已经被占用了(很重要)

对于版本号, npm使用业界标准的 {major}.{feature}.{patch} 模式

所以 1.4.1到1.4.2可能是修复个小bug

1.4.1到1.5.0可能是加了新功能

1.4.1到2.0.0的话, 可能就是变化很大的两个东西了.

Tips

如果你要发布包到npm, 相同的包名, 相同的版本号, 只能发布一次,

所以如果你修改了代码, 需要更新版本号才能publish,

具体修改哪一位, 要看你修改了多少东西.

description, keywords

这两个放在一起讲.

这两个字段都是用来在npm官网上搜索的, 区别是一个是字符串, 一个是字符串数组.

不难理解, npm会对description做分词搜索, 而对于 keywords会做精准搜索.

Tips

官方并未说明, 以上关于分词与否, 纯属猜测.

homepage

如果你有时间, 可以为你的包做一个官网之类的, 大型的项目常见.

bugs

这个字段并不是说这个包还有 bug, 首先我们看看例子

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

这个字段其实是提供给使用者上报 bugs的途径, 可以填一个email或者一个issue地址

Tips

如果你只想提供一个issue地址, 那么bugs可以只是一个字符串

license

这个......不想多说, 自行了解吧

author, contributors

这是关于作者或者其他开发人员信息的字段, 含义很好理解, 我们看一个例子:

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

author和contributors就是放置型如上面这样的对象来描述人物信息的, 区别是, author是单个, 而contributors是数组.

Tips

非必须信息, 可以出名以后再加.

files

这个不是必选项, 也并不常见, 但是很重要, 因为有配置这个信息会显得非常专业.

files是一个数组, 它描述了你 npm publish的时候推送到npm服务器的文件列表,支持目录和通配 比如

"files": [
    "LICENSE",
    "History.md",
    "Readme.md",
    "index.js",
    "lib/"
  ],

反过来, 你可以通过一个 .npmignore 文件来排除一些文件, 防止大量的垃圾文件推送到npm, 规则上和你用的gitignore是一样的.

Tips

如果你的项目下有 .gitignore 文件, 那么它也能充当.npmignore的功能.

这意味着, 如果没有特别的需求, 一个.gitignore就行了.

main

这个是一个重要属性,原文对这个描述比较绕, 实际上可以理解为 入口文件

"main":"./src/index.js",

以上面的例子来说, 如果你的包名是foo, 当用户代码require('foo')时,

相当于require了你包目录下的 ./src/index.js文件.

如果没有提供这个字段, 默认是项目根目录下的index.js

bin

这也是一个重要属性, 它定义了一系列可执行命令, 在全局安装的命令行包里尤其多见.

这里提供一个pm2的bin例子:

"bin": {
    "pm2": "./bin/pm2",
    "pm2-dev": "./bin/pm2-dev",
    "pm2-docker": "./bin/pm2-docker",
    "pm2-runtime": "./bin/pm2-runtime"
},

上面这个对象的意思是, 安装完以后, 输入pm2实际上是运行{模块所在目录}/bin/pm2, 以此类推.

带有bin信息的包, 在局部安装后, 可执行文件会在./node_modules/.bin下,

如果是全局安装, 可执行文件会在 $PATH 里对应npm那个目录下.

Tips

有些朋友安装node环境的方式比较奇怪, 没有把全局安装nodule的路径加到 $PATH里,

导致 npm install -g 以后提示命令找不到, 最好检查一下自己的$PATH

man

这里是manuel, 是手册的意思, 不是男人, 也不是上面说到的main

这个是指定一个(或多个)文件, 用于执行man {包名}时, 展现给用户的手册内容.

稍微有点linux基础都懂, 不细说.

directories

这个字段挺无语的, 它是一个object, 包含了lib`binmandocexampletest`等属性,

主要是用来告诉用户我的某些功能目录放在哪里, 也是一个显得专业的功能.

除此以外暂时没有实际应用.

"directories": {
    "bin": "./bin",
    "doc": "./doc",
    "lib": "./lib",
    "man": "./man"
},

repository

这个属性很明显, 是放置你的git地址的, 格式如下:

"repository" :{ 
    "type" : "git", 
    "url" : "https://github.com/npm/npm.git"
},

Tips

这个部分有一些缩写的方式, 自己看原文吧.

scripts

这个是重点!

"scripts": {
    "start": "node app.js",
    "any": "any command && exit 0",
},

以上两个配置, 提供了 npm start和npm run any两个命令对应的实际操作.

至于什么时候需要run什么时候不需要,

可以详细看 npm scripts, 这个够单独开一章来说明.

Tips

除了定义一些快捷命令, scripts 还有一些钩子性质的预定义命令,

如 preinstall , postinstall 可以在包安装前后 自动 执行一些操作

详细还是看上面的链接.

config

这是一个object结构, 定义了一些执行scripts时的配置参数之类, 和scripts属性关系很大, 个人目前还没用过, 等我研究好了再补充.

目前可以参考 npm-config

dependencies, devDependencies, peerDependencies

前两个大家很熟悉了, 不用展开讲了, 唯一需要提醒的是, 要自己判断什么包安装在dev就行.

值得注意的是 peerDependencies 这个并不常见的属性,

它是用于你这个包并不依赖模块A, 但是要使用你这个包, 必须当前项目装了A.

比如你的 my-project , 已经引入了people模块, 而还有一个people-fly, 必须你的my-project有用到people才可以用, 但是people-fly的源码里并没有直接使用people.

这时候, people-fly的package.json 里就会声明peerDependencies包含people

以上这一段多读几次应该能理解的.

bundledDependencies

这个是一个特定场景的属性, 我个人没用过.

bundledDependencies是一个字符串数组, 内容只能是在dependencies, devDependencies两个里面声明过的包才行.

这样可以在npm publish和npm pack的时候将一些依赖打包进去.

Tips:

单纯声明在dependencies里的包, 会在安装的时候, 再从npm那边安装一遍.

而打包了的, 就会在当前模块安装的时候, 就一并下载下来了.

具体怎么应用就自己想想吧, 我没用过.

optionalDependencies

可有可无的依赖?

npm通常会在某些依赖安装失败时报错, 中断操作, 而写在optionalDependencies的依赖则不会.

要妥善支持这个功能, 你的源码里面也要注意判断这些特定的依赖是否存在.

其实是很麻烦很扯淡的操作.

engines

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

这个属性可以声明你的包需要在怎样的node环境下运行 (npm也一样可以声明)

只不过,

只有在用户配置 npm 的engine-strict后, 才会有意义, 不然只会冒出一个 warning (程序员看不到 warning)

engineStrict

忽略, 最新的 npm已经废弃这个了.

os

看两个例子

"os" : [ "darwin", "linux" ]

"os" : [ "!win32" ]

显然意见就是操作系统的黑白名单,

比如你开发了一个工具, 只支持OSX, 不支持Windows (这合情合理!)

就可以通过这个来声明.

cpu

看两个例子

"cpu" : [ "x64", "ia32" ]

"cpu" : [ "!arm", "!mips" ]

不想解释了, 能玩到这个属性的人, 已经不需要看这个了.

private

这个设置为true, 就会无法npm publish,

怎么说呢, 有用的吧.?

publishConfig

定义一个包在发布到npm时的一些配置项,

要看具体细节请看 npm-config

更多...

package.json其实就是一个json文件, 你赋予一些字段更多的功能, 它就有了意义, 你自己开发功能的时候, 可以任意 发明 一些字段进去, 只要是你有用的就行.

比如我最近的一个项目, 在package.json里加了一个ci_cd对象, 你懂的.