寰宇网

package-lock.json[译]

为了更好的理解这个package-lock.json是干什么的,花了一点时间把npm官网这篇文档翻译了一下,第一次翻译英文文档,很多地方拿不准,用*标注了。

副标题

A manifestation of the manifest

一份配置清单的说明文件。

描述

package-lock.json 是一份在npm修改node_modules树或package.json时自动生成的文件。它精确地描述了这棵被生成的树(node_modules),这样后续的安装能生成完全一样的树,无论中间是否修改了依赖项。

这个文件是希望被提交到源码仓库的,它主要用于以下几种目的:

  • 描述一份关系依赖树,以便队友开发、部署和持续集成时都能够精确地安装出完全相同的一个依赖树。
  • 为用户提供一个”穿越时间”去查看之前的node_modules而无需提交node_modules目录本身(该目录一般情况下可能很大)。
  • 让树的变化能通过代码控制的diff表现得更明显。
  • 为之前安装过的package跳过重复的元数据(metadata)优化安装过程。

一个关键的细节是,不在项目顶层的package-lock.json文件将会被忽略,不能发表(应该是指在git里)。它和npm-shrinkwrap.json共享同个格式,在本质上它们其实是一样的,但是后者能够发表。除非使用一个部署的CLI工具或者使用发布流程制作线上包,否则是不推荐这样做的。

如果package-lock.json和npm-shrinkwrap.json同时出现在一个项目的顶层,package-lock.json将会被忽略。

文件格式

name(名称)

这个package的名字,它必须和package.json里的一样。

version(版本)

这个package的版本,它必须和package.json中的版本相匹配。

*lockfileVersion

一个整数版本,从1开始随着生成

*packageIntegrity

这是一个subresource integrity值从package.json中创建来。*No preprocessing of the package.json should be done。这个字符串应该被类似于ssri这样的模块生成出来。

*preserveSymlinks(保护的符号链接)

表明该安装完成且环境变量NODE_PRESERVE_SYMLINKS启用。安装程序一个使该属性和环境变量匹配。

dependencies(依赖)

一份包名(package name)到依赖对象(dependency object)的映射。依赖对象有以下属性:

version(版本)

这是一个说明符,来唯一标识一个包,且应该能通过此获取一份新的该包的副本。说明符有以下几种类别:

  • 打包好的依赖(bundle dependencies):不管来源,这个版本号的目的是纯粹提供信息。
  • registry资源:这是个版本号,如:1.2.3
  • git资源:这是一个指示着git中某次提交的标记。(比如:git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e
  • http的打包资源:这是一个指向压缩包的URL。(比如:https://example.com/example-1.3.0.tgz
  • 本地的打包资源:这是一个指向本地压缩包的文件URL。(比如:file:///opt/storage/example-1.3.0.tgz
  • 本地的链接源:这是一个指向本地文件URL的链接。(比如:file:libs/our-module

integrity(完整性)

这是一个关于该资源的标准的子资源完整性属性。

  • 如果是打包好的依赖将不会有该属性,不管其来源。
  • 如果是registry的资源,这个完整性(integrity)字段会由该registry来提供。* or if one wasn't provided the SHA1 in shasum(不知道什么意思)
  • 如果是一个git资源,这将是我们克隆的那次提交的哈希值。
  • 如果是个远程压缩包,将是该文件的SHA512的值。
  • 如果是本地压缩包,也是文件的SHA512的值。

resolved(已解决的)

  • 如果是打包好依赖,不会包含这个,不管来源。
  • 如果是registry资源,这将是该包的压缩包在registry的相对URL,如果压缩包的URL和registry的URL不同,将会是一个完整的URL。(比如百度自己的npm registry是http://registry.npm.baidu.com/,但安装包时从http://pnpm.baidu.com拉取,就会是一个完整的URL

bundled(打包的)

如果为true,这将是一个打包好的依赖,将从父模块安装。安装时该模块将在解压阶段直接从父模块提取,而不是像独立模块一样安装。

*dev(开发,这个属性在我这里的项目中统统为ture,没理解是干嘛的)

如果为true,那么这个依赖是顶层模块的开发依赖或者传递依赖。反之,则该依赖是一个顶层模块的开发依赖且是一个顶级的非开发模块的传递依赖。

*optional(可选项)

如果是true,这个依赖是一个可选的依赖。

*dependencies(依赖)

这个依赖的依赖,和顶级的属性一样。

写在最后

该翻译仅供参考,很多地方把握不准,结合原文和实际操作对比能忽略文字更好地理解。实际操作中还发现很多和该文档说明不一致的地方,比如dependency的属性,还可能有一个叫require的属性,目测和dependencies一样。