node.js package.json 和 package-lock.json 以及版本号说明

package.json 和 package-lock.json

package.json使用说明

在工程目录下使用 npm init 命令就可以初始化一个package.json文件。
以 nrm 包的 package.json 文件为例：

{
  "author": {
    "name": "Pana"
  },
  "bin": {
    "nrm": "./cli.js"
  },
  "bugs": {
    "url": "https://github.com/Pana/nrm/issues"
  },
  "bundleDependencies": false,
  "dependencies": {
    "async": "^1.5.2",
    "commander": "^2.9.0",
    "extend": "^3.0.0",
    "ini": "^1.1.0",
    "node-echo": "^0.1.1",
    "npm": "latest",
    "only": "0.0.2",
    "open": ">=6.0.0",
    "request": "^2.72.0"
  },
  "deprecated": false,
  "description": "NPM registry manager can help you easy and fast switch between different npm registries, now include: cnpm, taobao, nj(nodejitsu), edunpm",
  "homepage": "https://github.com/Pana/nrm",
  "keywords": [
    "NPM",
    "registry"
  ],
  "license": "MIT",
  "name": "nrm",
  "repository": {
    "type": "git",
    "url": "git://github.com/Pana/nrm.git"
  },
  "scripts": {
    "star": "npm star nrm"
  },
  "version": "1.2.1"
}

• name：包名

  name中不能有大写字母，不能以点或下划线开头。业务代码中，通过require(name)就可以引入对应的程序包了

• version：包的版本号。

  对于业务项目来说，这个往往不太重要，但是如果你要发布自己的项目，就要遵循版本号规范（参考上文版本号）。

• description：包的描述。

• homepage： 包的官网 url 。

• bugs：开发者的联系方式，代码库的issues地址等。如果代码使用者发现了bug，可以通过这个配置项找到提bug的地方。

• license：开源协议。

• author：包的作者姓名。

• contributors：包的其他贡献者姓名。

• scripts：指定了运行脚本命令的npm命令行缩写

  在命令行输入：npm run star，对应的命令就会被执行。

• dependencies：依赖包列表。如果依赖包没有安装，npm install 命令会自动将依赖包安装在 node_module 目录下。

  还可以这样设置：
  “dependencies”: { “foo”: “git+ssh://[email protected]:foo/foo.git#v1.0.1”, }

  这样的配置在下面这种场景十分有用：
  组内的许多项目都有同一个功能，把这个功能抽出来做成组件是很自然的想法。但是每个项目都有自己的代码库，公司也没有内部的npm库，组件应该放在哪里呢？可以专门为组件新建一个代码仓库，将组件放在这里开发、迭代。这样，各个项目都可以引用该组件：只需要在dependencies中将组件配置成上述的形式。至于组件的版本，可以通过git tag来控制。

• devDependencies：开发这个包时需要的依赖。

• bundledDependencies：打包时的依赖。

• repository：包代码存放的地方的类型，可以是 git 或 svn，git 可在 Github 上。

• main：main 字段指定了程序的主入口文件，require(‘moduleName’) 就会加载这个文件。这个字段的默认值是模块根目录下面的 index.js。

• keywords：关键字

• engines：指定项目所依赖的node环境、npm版本等。

• private：如果设为true，无法通过npm publish发布代码。

为什么会有package-lock.json文件

• 项目开发过程中，在拿到别人的代码时，工程目录中可能没有node_modules目录，但是有package.json文件，这时需要使用 npm install 命令批量下载项目所需要的依赖（第三方包）。

• 在新开发一个项目时，我们如果使用 npm install xxx 命令一个个下载所需要的第三方包未免太过麻烦。这时我们可以在 package.json 文件的 dependencies 属性中手动添加需要下载的第三方包以及版本号，然后执行 npm install 命令批量下载这些第三方包。

• 但是package.json 文件在执行 npm install 命令下载项目依赖时只能锁定主版本号，也就是版本号的第一位，并不能锁定后面的小版本，拉取的都是该主版本下的最新的版本。

  package.json 中的 dependencies：

   "dependencies": {
      "async": "~1.5.2",
      "commander": "^2.9.0",
      "extend": "^3.0.0",
      "ini": "~1.1.0",
      }
  

• 为了稳定性考虑我们几乎是不敢随意升级依赖包的，如果换包导致兼容性bug出现很难排查，这将导致多出来很多工作量，测试/适配等。所以 package-lock.json 文件出来了，当你每次安装一个依赖的时候就锁定在你安装的这个版本。

• package-lock.json 是在新版本中执行 npm install xxx 命令的时候生成的一份文件，用以记录当前状态下实际安装的各个 npm package 的具体来源和版本号。

• package-lock.json 文件的作用是锁定安装时的包的版本号，并且需要上传到 git。这样的话在一个新的机器上、或者新的下载源，只要按照这个 package-lock.json 所标示的具体版本下载依赖库包，就能确保所有库包与你上次安装的完全一样。

  package-lock.json 中的 dependencies：

  "dependencies": {
      "acorn": {
        "version": "5.7.4",
        "resolved": "https://registry.npm.taobao.org/acorn/download/acorn-5.7.4.tgz?cache=0&sync_timestamp=1591869455923&other_urls=https%3A%2F%2Fregistry.npm.taobao.org%2Facorn%2Fdownload%2Facorn-5.7.4.tgz",
        "integrity": "sha1-Po2KmUfQWZoXltECJddDL0pKz14="
      }
   }
  

• 如果想升级某个包，在以前可能就是直接改 package.json 里面的版本，然后再执行 npm install 命令。但是 5 版本后就不支持这样做了，因为版本已经锁定在 package-lock.json 里。

  即使我们这样操作之后，发现 package.json 文件和 package.json 文件里对应版本号已经改变，但是在node_modules目录下的第三方包并没有升级，还是原先的版本。

• 我们可以使用 npm install [email protected] 去更新我们的依赖，然后 package-lock.json 也会随之更新。

• 或者使用 npm update [xxx] 可以将 package.json 文件 dependencies 属性中第三方包升级至最新版本。

  版本号前面是“~”：更新至最新的补丁版本
  版本号前面是“^”：更新至最新的次版本
  版本号前面没有字符：不更新

版本号（参考地址）

使用 npm 下载和发布代码时都会接触到版本号。npm 使用语义版本号来管理代码，语义版本号分为 X.Y.Z 三位，分别代表主版本号、次版本号和补丁版本号。当代码变更时，版本号按以下原则更新。

• 如果只是修复bug，需要更新Z位。

• 如果是新增了功能，但是向下兼容，需要更新Y位。

• 如果有大变动，向下不兼容，需要更新X位。

  版本号中的“~” 和 “^”

  • ~1.2.2：表示安装1.2.x的最新版本（不低于1.2.2），但是不安装1.3.x，也就是说安装时不改变主版本号和次版本号。
  • ˆ1.2.2：表示安装1.x.x的最新版本（不低于1.2.2），但是不安装2.x.x，也就是说安装时不改变主版本号。需要注意的是，如果主版本号为0，则 “^” 和 “~” 行为相同，这是因为此时处于开发阶段，即使是次版本号变动，也可能带来程序的不兼容。
  • 1.2.2：表示安装1.2.2版本，使用 npm update 命令时不会更新此类包