深入了解package.json

backlight46944
1,242 阅读7分钟
原文链接： techblog.sishuxuefu.com

深入了解package.json

本文由我们团队肖建朋总结

目录

[TOC]

每个nodeJS项目的根目录下面，一般都有一个package.json文件，定义了这个项目所需要的各种模块，以及项目的配置信息（比如名称、版本、许可证等元数据）。npm install命令根据这个配置文件，自动下载所需的模块，也就是配置项目所需的运行和开发环境。本文带着大家详细了解一下这个package.json文件。我们先来看下完整package.json有哪些内容：

{
    "name": "Hello World",
    "version": "0.0.1",
    "author": "张三",
    "description": "第一个node.js程序",
    "keywords":["node.js","javascript"],
    "repository": {
        "type": "git",
        "url": "https://path/to/url"
    },
    "license":"MIT",
    "engines": {"node": "0.10.x"},
    "bugs":{"url":"http://xxx","email":"xxx@xxx.com"},
    "contributors":[{"name":"xxx","email":"xxx@xxx.com"}],
    "scripts": {
        "start": "node index.js"
    },
    "dependencies": {
        "express": "latest",
        "mongoose": "~3.8.3",
        "handlebars-runtime": "~1.0.12",
        "express3-handlebars": "~0.5.0",
        "MD5": "~1.2.0"
    },
    "devDependencies": {
        "bower": "~1.2.8",
        "grunt": "~0.4.1",
        "grunt-contrib-concat": "~0.3.0",
        "grunt-contrib-jshint": "~0.7.2",
        "grunt-contrib-uglify": "~0.2.7",
        "grunt-contrib-clean": "~0.5.0",
        "browserify": "2.36.1",
        "grunt-browserify": "~1.3.0",
    }
}

基础篇

初始化package.json

输入命令npm init回车，然后按照提示一步步确认信息

步骤如下：

package name: 输入要创建项目的名称

version: (1.0.1)版本号,可以自定义，要遵循“大版本.次要版本.小版本”的格式

decription: 项目描述

entrypoint: (index.js)  项目入口文件,可以自定义

test command:

git repository: git仓库地址

keywords: 关键字

author: 作者

license: (ISC)

完成后生成的package.json如下：

{
  "name": "test",
  "version": "0.0.1",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT"
}

scripts指定了运行脚本命令的npm命令行缩写，比如start指定了运行npm run start时，所要执行的命令。比如我在一个node项目中添加的缩写命令：

"scripts": {
    "fix": "eslint --fix ./",
    "lint": "eslint lint ./",
    "start": "node ./src/app.js",
    "dev": "nodemon ./src/app.js -- ",
    "pm2": "pm2 start ./src/app.js"
  }

从这个文件可以看出package.json文件就是一个大的JSON对象，该对象的每一个成员就是当前项目的一个设置。比如name就是项目名称，version 就是版本号。

当然，如果你足够熟悉，可以手动编写。

目前的package.json文件还很简陋，与我们平常用的还少了很多东西，接下来就一步一步把它丰富起来。

dependencies和devDependencies

我们经常会在项目的package.json文件中看到这两个块，里面引入了各种各样的依赖包，name他们的区别是什么呢？

它们都指向一个对象。该对象的各个成员，分别由模块名和对应的版本要求组成，表示依赖的模块及其版本范围。

  • dependencies字段指定了项目运行所依赖的模块，

  • devDependencies指定项目开发所需要的模块。

"dependencies": {
    "elasticsearch": "^16.1.1",
    "koa": "^2.7.0",
    "koa-bodyparser": "^4.2.1",
    "koa-router": "^7.4.0",
    "koa-static": "^5.0.0",
    "koa2-cors": "^2.0.6",
    "mysql": "^2.17.1",
    "qiniu": "^7.2.2",
    "uuid": "^3.3.2"
  },
  "devDependencies": {
    "nodemon": "^1.19.1",
    "atob": "^2.1.2",
    "node-blob": "^0.0.2",
    "qiniu-js": "^2.5.4"
  }

依赖包版本号的限定

  • 指定版本： 比如1.2.2，遵循“大版本.次要版本.小版本”的格式规定，安装时只安装指定版本。

  • 波浪号（tilde）+指定版本：比如~1.2.2，表示安装1.2.x的最新版本（不低于1.2.2），但是不安装1.3.x，也就是说安装时不改变大版本号和次要版本号。

  • 插入号（caret）+指定版本：比如ˆ1.2.2，表示安装1.x.x的最新版本（不低于1.2.2），但是不安装2.x.x，也就是说安装时不改变大版本号。需要注意的是，如果大版本号为0，则插入号的行为与波浪号相同，这是因为此时处于开发阶段，即使是次要版本号变动，也可能带来程序的不兼容。

  • latest：安装最新版本

安装模块

$ npm install express --save
$ npm install express --save-dev

上面代码表示单独安装express模块，--save参数表示将该模块写入dependencies属性，--save-dev表示将该模块写入devDependencies属性。

到这里以后，目前的package.json文件，已经足够很多小项目使用。

{
  "name": "apm-server",
  "version": "1.0.0",
  "author": "",
  "license": "MIT",
  "description": "XXXX",
  "main": "src/app.js",
  "scripts": {
    "fix": "eslint --fix ./",
    "lint": "eslint lint ./",
    "start": "node ./src/app.js",
    "dev": "nodemon ./src/app.js -- ",
    "pm2": "pm2 start ./src/app.js"
  },
  "dependencies": {
    "elasticsearch": "^16.1.1",
    "koa": "^2.7.0",
    "koa-bodyparser": "^4.2.1",
    "koa-router": "^7.4.0",
    "koa-static": "^5.0.0",
    "koa2-cors": "^2.0.6",
    "mysql": "^2.17.1",
    "qiniu": "^7.2.2",
    "uuid": "^3.3.2"
  },
  "devDependencies": {
    "nodemon": "^1.19.1",
    "atob": "^2.1.2",
    "node-blob": "^0.0.2",
    "qiniu-js": "^2.5.4"
  }
}

进阶篇

peerDependencies

有时你的项目会遇到项目和依赖的模块同时依赖的另一个模块，但是他们各自依赖的版本却不同，

比如，你的项目依赖A模块和B模块的1.0版，而A模块本身又依赖B模块的2.0版。

大多数情况下，这不构成问题，B模块的两个版本可以并存，同时运行。但是，有一种情况，会出现问题，就是这种依赖关系将暴露给用户。

最典型的场景就是插件，比如A模块是B模块的插件。用户安装的B模块是1.0版本，但是A插件只能和2.0版本的B模块一起使用。这时，用户要是将1.0版本的B的实例传给A，就会出现问题。因此，需要一种机制，在模板安装的时候提醒用户，如果A和B一起安装，那么B必须是2.0模块。

peerDependencies字段，就是用来供插件指定其所需要的主工具的版本。

{
  "name": "chai-as-promised",
  "peerDependencies": {
    "chai": "1.x"
  }
}

上面代码指定，安装chai-as-promised模块时，主程序chai必须一起安装，而且chai的版本必须是1.x。如果你的项目指定的依赖是chai的2.0版本，就会报错。

总结一句话：peerDependencies的目的是提示宿主环境去安装满足插件peerDependencies所指定依赖的包，然后在插件import或者require所依赖的包的时候，永远都是引用宿主环境统一安装的npm包，最终解决插件与所依赖包不一致的问题。

举个例子，就拿目前基于react的ui组件库ant-design@3.x来说，因该ui组件库只是提供一套react组件库，它要求宿主环境需要安装指定的react版本。具体可以看它package.json中的配置：

  "peerDependencies": {
    "react": ">=16.0.0",
    "react-dom": ">=16.0.0"
  }

它要求宿主环境安装react@>=16.0.0和react-dom@>=16.0.0的版本，而在每个antd组件的定义文件顶部：

import * as React from 'react';
import * as ReactDOM from 'react-dom';

组件中引入的react和react-dom包其实都是宿主环境提供的依赖包。

bin

用来指定各个内部命令对应的可执行文件的位置。

"bin": {
  "someTool": "./bin/someTool.js"
}

someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。Npm会寻找这个文件，在node_modules/.bin/目录下建立符号链接。在上面的例子中，someTool.js会建立符号链接npm_modules/.bin/someTool。由于node_modules/.bin/目录会在运行时加入系统的PATH变量，因此在运行npm时，就可以不带路径，直接通过命令来调用这些脚本。

上面讲的scripts中的缩写命令可以简化，如：

scripts: {  
  start: './node_modules/someTool/someTool.js build'
}

// 简写为
scripts: {  
  start: 'someTool build'
}

所有node_modules/.bin/目录下的命令，都可以用npm run [命令]的格式运行。在命令行下，键入npm run，然后按tab键，就会显示所有可以使用的命令。

config

config用于添加命令行的环境变量

如：

{
  "name" : "foo",
  "config" : { "port" : "8080" },
  "scripts" : { "start" : "node server.js" }
}

使用：

http
  .createServer(...)
  .listen(process.env.npm_package_config_port)

用户执行npm run start命令时，这个脚本就可以得到值。

$ npm run start

用户可以改变这个值。

$ npm config set foo:port 80

扩展篇

browser字段

browser指定该模板供浏览器使用的版本。Browserify这样的浏览器打包工具，通过它就知道该打包那个文件。

"browser": {
  "tipso": "./node_modules/tipso/src/tipso.js"
},

engines 字段

engines字段指明了该模块运行的平台，比如 Node 的某个版本或者浏览器。

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

该字段也可以指定适用的npm版本。

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

man字段

man用来指定当前模块的man文档的位置。

"man" :[ "./doc/calc.1" ]

preferGlobal字段

preferGlobal的值是布尔值，表示当用户不将该模块安装为全局模块时（即不用–global参数），要不要显示警告，表示该模块的本意就是安装为全局模块。

style字段

style指定供浏览器使用时，样式文件所在的位置。样式文件打包工具parcelify，通过它知道样式文件的打包位置。

"style": [
  "./node_modules/tipso/src/tipso.css"
]
avatar
文章
阅读
粉丝