Node学习之package.json

什么是package.json

Node.js项目遵循模块化的架构，当我们创建一个Node.js项目，意味着创建了一个模块，这个模块的描述文件，被称为package.json

它包含了运行项目所需要的各种依赖、项目配置信息

创建package.json

快速创建

npm init -y

package.json

{
  "name": "demo",
  "version": "1.0.0",
  "description": "",
  "main": "main.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

字段介绍

必填字段 name & version

如果你打算发布npm包，name和verson是package.json中的必填字段，它们组成一个npm模块的唯一标识。

如果你不打算发布npm包，则这两个字段是可选的

name

name字段定义模块的名称

官方规则：

• 名称必须小于等于214个字符
• 名称不能以点或下划线开头。
• 不得包含大写字母
• 该名称最终成为URL，命令行参数和文件夹名称的一部分。 因此，该名称不能包含任何非URL安全的字符。（使用validate-npm-package-name包检测模块名是否合法）

官方建议：

• 不能与Node核心模块同名
• name名不能与npm其他模块名重复，可以执行npm view <packageName>查看模块名是否已被使用，未被使用会抛出404错误。或者去https://www.npmjs.com/上搜索模块名
• 不要再名称中添加js或node
• 名称可能会作为参数传递给require()，因此它应该简短，并具有描述性

名称可以可选的以范围为前缀，例如@babel/present

version

npm包中的模块版本都需要遵循 SemVer 语义化版本控制规范，该规范采用X.Y.Z格式，X、Y、Z均为非负整数，且禁止在数字前补零

• X 主版本号：有大变动，且向下不兼容
• Y 次版本号：新增功能，但是向下兼容
• Z 补丁版本号：修复问题

先行版本

当某个版本改动比较大、并非稳定而且可能无法满足预期的兼容性需求时，可能需要先发布一个先行版本。

先行版本号一般加到修订号后，通过-连接一串以.分隔的标识符和版本编译信息，如：3.10.2-beta.13。

标识符：

• 内部版本(alpha)
• 公测版本(beta)
• 正式版本的候选版本(rc:Release candiate)

校验版本号

版本号必须可以通过node-semver进行解析

npm view <packageName> version # 查看最新版本
npm view <packageName> versions # 查看历史版本

描述信息 description & keywords

• description字段添加模块的描述信息
• keywords字段添加模块的关键字

使用npm检索模块时会对这两个字段进行匹配

安装项目依赖 dependencies & devDependencies

dependencies、 devDependencies是包含项目依赖的对象，对象将包名key映射到版本范围value。

• dependencies字段指定了项目运行时所依赖的模块（生产环境使用），如antd moment loadsh等插件库
  • 当把项目作为一个npm包时，用户安装时只会安装dependencies中的依赖
• devDependencies字段指定了项目开发时所依赖的模块（开发环境使用），如webpack babel typescript等
  • 开发时对代码校验、编译打包等操作时需要的依赖，在提交线上运行时并不需要，所以放到devDependencies中。例如开发自己的项目而不是对外的包，上面的antd moment loadsh会被打包到发布代码中，也可以放到devDependencies中

添加依赖并记录到package.json

# npm
npm install <packageName> --save # 写入dependencies属性
npm install <packageName> --save-dev # 写入devDependencies属性

# yarn
yarn add <packageName> # 写入dependencies属性
yarn add <packageName> --dev # 写入devDependencies属性

线上或开发环境安装package.json中的依赖

# npm
npm install # 安装所有依赖（dependencies 和 devDependencies）
npm install --production # 安装生产依赖（dependencies）

# yarn
yarn install # 安装所有依赖（dependencies 和 devDependencies）
yarn install --production # 安装生产依赖（dependencies）

版本范围

[标识符][主版本号].[次版本号].[补丁版本号]版本号标识符定义在安装依赖时，允许更新到的版本范围

version

完全比配版本号

比较version

• >version 大于版本号的范围
• >=version 大于等于版本号的范围
• <version小于版本号的范围
• <=version小于等于版本号的范围

~version 大约等于

示例	版本范围	说明
~X.Y.Z	X.Y.Z<=version<X.(Y+1).0	允许补丁版本号升级，无上限，下限为Z
~X.Y	X.Y.0<=version<X.(Y+1).0	允许补丁版本号升级，无上限
~X	X.0.0<=version<(X+1).0.0	允许次版本号和补丁版本号升级，无上限

^version与版本兼容

在未缺失的版本号中，从左往右，找到第一个不为0的版本号，它后面的版本号允许升级到最新。

版本号缺失，视为0

次版本号和补丁版本号都缺失，同时主版本为0，补丁版本号视为1

版本号缺失，允许升级

示例	版本范围	说明
^1.3.4	1.3.4<=version<2.0.0	主版本号不为0，允许次版本号和补丁版本号升级，有下限，无上限
^0.3.4	0.3.4<=version<0.4.0	主版本号为0，次版本号不为0，允许补丁版本号升级，有下限，无上限
^0.0.4	0.0.4<=version<0.0.5	主版本号和次版本号都为0，无法升级模块
^0.3	0.3.0<=version<0.4.0	主版本号为0，次版本号不为0，补丁版本号缺失视为0，允许升级补丁版本号，无上限
^0	0.0.1<=version<1.0.0	主版本号为0，次版本号和补丁版本号缺失，补丁版本号视为1，允许次版本号和补丁版本号升级，次版本号下限1
^1.3	1.3.0<=version<2.0.0	主版本号不为0，允许次版本号和补丁版本号升级，次版本号下限3
^1	1.0.0<=version<2.0.0	主版本号不为0，次版本号和补丁版本号缺失，都视为0，允许次版本号和补丁版本号升级

脚本管理 scripts

生命周期事件

scripts包含在包的生命周期中各个时间运行的脚本命令。

• key是生命周期时间，install、postinstall、publish等
• value是时间点运行的命令

简化终端命令

scripts还是包含自定义脚本命令

• key可以通过npm run <key>运行的脚本
• value为实际运行的命令

默认值

• start：node server.js
  • 如果项目根目录下有一个server.js文件，则npm run start(可省略为npm start)将默认执行node server.js命令
• install：node-gyp rebuild
  • 如果项目根目录下有一个binding.gyp文件，并且还未定义install和preinstall脚本，npm将默认使用node-gyp rebuild编译install命令

package.json vars

scripts运行的脚本可以访问到package.json定义的属性

访问方式：process.env.npm_package_[propName]

定义项目入口 main

• 如果你的项目是一个npm包，当用户安装包后，require()返回的是main字段中所列出的文件的module.exports属性
• 当不指定main字段时，默认时模块根目录下面的index.js文件

发布文件配置 files

• files是一个包含文件/目录列表的数组
• 用于描述使用npm publish命令推送到npm服务器的文件列表，如果指定为文件夹，则文件夹内所有内容都会包含进来。省略该字段，默认为[*]
• 也就是安装依赖时，下载的文件内容
• 另外还可以通过配置一个.npmignore文件来排除一些文件，防止大量的垃圾文件推送到npm上。工作原理与.gitignore一样，如果存在.gitignore，缺少.npmignore，则改用.gitignore的内容。
• 无法通过.gitignore和.gitignore排除files字段中包含的文件。

禁止发布 private

设置private为true，npm将拒绝发布该私有模块，可以放置非开源项目意外发布

指定模块适用系统 os

如果模块只能运行在A系统，我们需要保证其他系统的用户不会安装到该模块，设置os可以指定模块适用的系统，或指定不能安装的系统黑名单

"os": ["darwin","linux"] # 适用系统
"os": ["!win32"] # 黑名单系统，此列表中的系统安装模块会报错

指定模块适用CPU架构 cpu

同os一样配置适用列表和黑名单列表

指定项目node版本 engines

engines可以指定node版本或npm版本，在安装时对不适用的版本发出警告

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

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

自定义命令 bin

bin字段指定内部命令对应的可执行文件的位置。

例如：

• vue-cli的vue create
• create-react-app的create-react-app

当用户安装带有bin字段的包时

• 如果是全局安装，npm将使用符号链接把这些文件链接到usr/local/node_modules/.bin/
• 如果是本地安装，会链接到./node_modules/.bin/
  示例：

"bin":{
  "myapp": "./cli.js"
}

node node_modules/.bin/myapp

• 当需要node环境时需要加上node前缀
• 使用node执行，就要对命令添加路径前缀node_modules/.bin/，否则就会在当前路径下寻找cli.js

在可执行文件的第一行加上#!/usr/bin/env node，用于指明该脚本要使用node执行

• /usr/bin/env 告诉用户到path目录下去寻找node
• #!/usr/bin/env node 可以让系统动态的去查找node，以解决不同用户设置不一致的问题

加上后，就可以直接使用myapp执行了

参考

重新认识 package.json
npm-package.json