package-lock.json

清单的体现

描述

¥Description

对于 npm 修改 node_modules 树或 package.json 的任何操作，都会自动生成 package-lock.json。它描述了生成的确切树，以便后续安装能够生成相同的树，而不管中间依赖更新如何。

¥package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

该文件旨在提交到源存储库中，并用于各种目的：

¥This file is intended to be committed into source repositories, and serves various purposes:

• 描述依赖树的单一表示，以保证团队成员、部署和持续集成安装完全相同的依赖。

  ¥Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.

• 为 "time-travel" 的用户提供一种工具，使其无需提交目录本身即可进入 node_modules 的先前状态。

  ¥Provide a facility for users to "time-travel" to previous states of node_modules without having to commit the directory itself.

• 通过可读的源代码控制差异促进树变化的更大可见性。

  ¥Facilitate greater visibility of tree changes through readable source control diffs.

• 通过允许 npm 跳过以前安装的包的重复元数据解析来优化安装过程。

  ¥Optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.

• 从 npm v7 开始，lockfiles 包含足够的信息来获得包树的完整图片，减少了读取 package.json 文件的需要，并允许显着提高性能。

  ¥As of npm v7, lockfiles include enough information to gain a complete picture of the package tree, reducing the need to read package.json files, and allowing for significant performance improvements.

当 npm 创建或更新 package-lock.json 时，它将从 package.json 推断行结尾和缩进，以便两个文件的格式匹配。

¥When npm creates or updates package-lock.json, it will infer line endings and indentation from package.json so that the formatting of both files matches.

package-lock.json 与 npm-shrinkwrap.json

¥package-lock.json vs npm-shrinkwrap.json

这两个文件具有相同的格式，并且在项目的根目录中执行类似的功能。

¥Both of these files have the same format, and perform similar functions in the root of a project.

不同的是，package-lock.json 不能发布，如果在根项目以外的任何地方发现都会被忽略。

¥The difference is that package-lock.json cannot be published, and it will be ignored if found in any place other than the root project.

相反，npm-shrinkwrap.json 允许发布，并从遇到的点定义依赖树。除非部署 CLI 工具或以其他方式使用发布过程来生成生产包，否则不建议这样做。

¥In contrast, npm-shrinkwrap.json allows publication, and defines the dependency tree from the point encountered. This is not recommended unless deploying a CLI tool or otherwise using the publication process for producing production packages.

如果项目的根目录中同时存在 package-lock.json 和 npm-shrinkwrap.json，则 npm-shrinkwrap.json 将优先，而 package-lock.json 将被忽略。

¥If both package-lock.json and npm-shrinkwrap.json are present in the root of a project, npm-shrinkwrap.json will take precedence and package-lock.json will be ignored.

隐藏的锁文件

¥Hidden Lockfiles

为了避免重复处理 node_modules 文件夹，从 v7 开始的 npm 使用 node_modules/.package-lock.json 中存在的 "hidden" 锁定文件。这包含有关树的信息，如果满足以下条件，则用于代替读取整个 node_modules 层次结构：

¥In order to avoid processing the node_modules folder repeatedly, npm as of v7 uses a "hidden" lockfile present in node_modules/.package-lock.json. This contains information about the tree, and is used in lieu of reading the entire node_modules hierarchy provided that the following conditions are met:

• 它引用的所有包文件夹都存在于 node_modules 层次结构中。

  ¥All package folders it references exist in the node_modules hierarchy.

• node_modules 层次结构中不存在未在锁定文件中列出的包文件夹。

  ¥No package folders exist in the node_modules hierarchy that are not listed in the lockfile.

• 文件的修改时间至少与它引用的所有包文件夹一样新。

  ¥The modified time of the file is at least as recent as all of the package folders it references.

也就是说，隐藏的锁定文件只有在作为最新更新包树的一部分创建时才相关。如果另一个 CLI 以任何方式改变了树，这将被检测到，并且隐藏的锁定文件将被忽略。

¥That is, the hidden lockfile will only be relevant if it was created as part of the most recent update to the package tree. If another CLI mutates the tree in any way, this will be detected, and the hidden lockfile will be ignored.

请注意，可以手动更改包的内容，使包文件夹的修改时间不受影响。例如，如果你将文件添加到 node_modules/foo/lib/bar.js，那么 node_modules/foo 上的修改时间将不会反映此更改。如果是手动编辑 node_modules 中的文件，一般最好删除 node_modules/.package-lock.json 中的文件。

¥Note that it is possible to manually change the contents of a package in such a way that the modified time of the package folder is unaffected. For example, if you add a file to node_modules/foo/lib/bar.js, then the modified time on node_modules/foo will not reflect this change. If you are manually editing files in node_modules, it is generally best to delete the file at node_modules/.package-lock.json.

由于较旧的 npm 版本忽略了隐藏的锁定文件，因此它不包含 "normal" 锁定文件中存在的向后兼容性功能。也就是说，它是 lockfileVersion: 3，而不是 lockfileVersion: 2。

¥As the hidden lockfile is ignored by older npm versions, it does not contain the backwards compatibility affordances present in "normal" lockfiles. That is, it is lockfileVersion: 3, rather than lockfileVersion: 2.

处理旧的锁文件

¥Handling Old Lockfiles

当 npm 在包安装过程中检测到来自 npm v6 或更早版本的锁文件时，它会自动更新以从 node_modules 树或（在空 node_modules 树或非常旧的锁文件格式的情况下）npm 注册表中获取缺失的信息。

¥When npm detects a lockfile from npm v6 or before during the package installation process, it is automatically updated to fetch missing information from either the node_modules tree or (in the case of empty node_modules trees or very old lockfile formats) the npm registry.

文件格式

¥File Format

name

这是一个包锁的包的名称。这将匹配 package.json 中的内容。

¥The name of the package this is a package-lock for. This will match what's in package.json.

version

这是包锁定的包的版本。这将匹配 package.json 中的内容。

¥The version of the package this is a package-lock for. This will match what's in package.json.

lockfileVersion

一个整数版本，从 1 开始，带有此文档的版本号，其语义在生成此 package-lock.json 时使用。

¥An integer version, starting at 1 with the version number of this document whose semantics were used when generating this package-lock.json.

请注意，npm v7 中的文件格式发生了显着变化，以跟踪原本需要在 node_modules 或 npm 注册表中查找的信息。npm v7 生成的锁文件将包含 lockfileVersion: 2。

¥Note that the file format changed significantly in npm v7 to track information that would have otherwise required looking in node_modules or the npm registry. Lockfiles generated by npm v7 will contain lockfileVersion: 2.

• 没有提供版本：来自 npm v5 之前的 npm 版本的 "ancient" shrinkwrap 文件。

  ¥No version provided: an "ancient" shrinkwrap file from a version of npm prior to npm v5.

• 1：npm v5 和 v6 使用的 lockfile 版本。

  ¥1: The lockfile version used by npm v5 and v6.

• 2：npm v7 和 v8 使用的锁文件版本。向后兼容 v1 锁文件。

  ¥2: The lockfile version used by npm v7 and v8. Backwards compatible to v1 lockfiles.

• 3：npm v9 及以上版本使用的锁文件版本。向后兼容 npm v7。

  ¥3: The lockfile version used by npm v9 and above. Backwards compatible to npm v7.

npm 将始终尝试从锁定文件中获取任何数据，即使它不是它旨在支持的版本。

¥npm will always attempt to get whatever data it can out of a lockfile, even if it is not a version that it was designed to support.

packages

这是一个将包位置映射到包含该包信息的对象的对象。

¥This is an object that maps package locations to an object containing the information about that package.

根项目通常使用 "" 键列出，所有其他包都列出了它们在根项目文件夹中的相对路径。

¥The root project is typically listed with a key of "", and all other packages are listed with their relative paths from the root project folder.

包描述符具有以下字段：

¥Package descriptors have the following fields:

• version:package.json 中找到的版本

  ¥version: The version found in package.json

• resolved:实际解析包的地方。对于从注册表中获取的包，这将是一个 tarball 的 url。在 git 依赖的情况下，这将是带有提交 sha 的完整 git url。在链接依赖的情况下，这将是链接目标的位置。registry.npmjs.org 是一个神奇的值，意思是 "当前配置的注册表"。

  ¥resolved: The place where the package was actually resolved from. In the case of packages fetched from the registry, this will be a url to a tarball. In the case of git dependencies, this will be the full git url with commit sha. In the case of link dependencies, this will be the location of the link target. registry.npmjs.org is a magic value meaning "the currently configured registry".

• integrity:在此位置解压缩的工件的 sha512 或 sha1 标准子资源完整性 字符串。

  ¥integrity: A sha512 or sha1 Standard Subresource Integrity string for the artifact that was unpacked in this location.

• link:一个标志，表明这是一个符号链接。如果存在，则不指定其他字段，因为链接目标也将包含在锁定文件中。

  ¥link: A flag to indicate that this is a symbolic link. If this is present, no other fields are specified, since the link target will also be included in the lockfile.

• dev, optional, devOptional:如果包严格属于 devDependencies 树，则 dev 为真。如果它严格属于 optionalDependencies 树，则设置 optional。如果它既是 dev 依赖又是非开发依赖的 optional 依赖，则将设置 devOptional。（dev 依赖的 optional 依赖将同时设置 dev 和 optional。）

  ¥dev, optional, devOptional: If the package is strictly part of the devDependencies tree, then dev will be true. If it is strictly part of the optionalDependencies tree, then optional will be set. If it is both a dev dependency and an optional dependency of a non-dev dependency, then devOptional will be set. (An optional dependency of a dev dependency will have both dev and optional set.)

• inBundle:指示包是打包依赖的标志。

  ¥inBundle: A flag to indicate that the package is a bundled dependency.

• hasInstallScript:指示包具有 preinstall、install 或 postinstall 脚本的标志。

  ¥hasInstallScript: A flag to indicate that the package has a preinstall, install, or postinstall script.

• hasShrinkwrap:指示包具有 npm-shrinkwrap.json 文件的标志。

  ¥hasShrinkwrap: A flag to indicate that the package has an npm-shrinkwrap.json file.

• bin、许可证、引擎、依赖、可选依赖：来自 package.json 的字段

  ¥bin, license, engines, dependencies, optionalDependencies: fields from package.json

dependencies

支持使用 lockfileVersion: 1 的 npm 版本的旧数据。这是包名称到依赖对象的映射。因为对象结构是严格分层的，所以在某些情况下，符号链接依赖很难表示。

¥Legacy data for supporting versions of npm that use lockfileVersion: 1. This is a mapping of package names to dependency objects. Because the object structure is strictly hierarchical, symbolic link dependencies are somewhat challenging to represent in some cases.

如果存在 packages 部分，npm v7 会完全忽略此部分，但会保持更新以支持在 npm v6 和 npm v7 之间切换。

¥npm v7 ignores this section entirely if a packages section is present, but does keep it up to date in order to support switching between npm v6 and npm v7.

依赖对象具有以下字段：

¥Dependency objects have the following fields:

• version:根据包的性质而变化的说明符，可用于获取它的新副本。

  ¥version: a specifier that varies depending on the nature of the package, and is usable in fetching a new copy of it.

  • 打包的依赖：无论来源如何，这是一个纯粹用于提供信息的版本号。

    ¥bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.

  • 注册表来源：这是一个版本号。（例如，1.2.3）

    ¥registry sources: This is a version number. (eg, 1.2.3)

  • git 来源：这是一个带有已解决提交的 git 说明符。（例如，git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e）

    ¥git sources: This is a git specifier with resolved committish. (eg, git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e)

  • http 压缩包来源：这是压缩包的 URL。（例如，https://example.com/example-1.3.0.tgz）

    ¥http tarball sources: This is the URL of the tarball. (eg, https://example.com/example-1.3.0.tgz)

  • 本地压缩包来源：这是 tarball 的文件 URL。（例如 file:///opt/storage/example-1.3.0.tgz）

    ¥local tarball sources: This is the file URL of the tarball. (eg file:///opt/storage/example-1.3.0.tgz)

  • 本地链接来源：这是链接的文件 URL。（例如 file:libs/our-module）

    ¥local link sources: This is the file URL of the link. (eg file:libs/our-module)

• integrity:在此位置解压缩的工件的 sha512 或 sha1 标准子资源完整性 字符串。对于 git 依赖，这是提交 sha。

  ¥integrity: A sha512 or sha1 Standard Subresource Integrity string for the artifact that was unpacked in this location. For git dependencies, this is the commit sha.

• resolved:对于注册表源，这是 tarball 相对于注册表 URL 的路径。如果 tarball URL 与注册表 URL 不在同一台服务器上，那么这是一个完整的 URL。registry.npmjs.org 是一个神奇的值，意思是 "当前配置的注册表"。

  ¥resolved: For registry sources this is path of the tarball relative to the registry URL. If the tarball URL isn't on the same server as the registry URL then this is a complete URL. registry.npmjs.org is a magic value meaning "the currently configured registry".

• bundled:如果为 true，则这是打包的依赖，将由父模块安装。安装时，此模块将在提取阶段从父模块中提取，而不是作为单独的依赖安装。

  ¥bundled: If true, this is the bundled dependency and will be installed by the parent module. When installing, this module will be extracted from the parent module during the extract phase, not installed as a separate dependency.

• dev:如果为真，则此依赖要么是仅顶层模块的开发依赖，要么是一个传递依赖。这对于既是顶层的开发依赖又是顶层非开发依赖的传递依赖的依赖是错误的。

  ¥dev: If true then this dependency is either a development dependency ONLY of the top level module or a transitive dependency of one. This is false for dependencies that are both a development dependency of the top level and a transitive dependency of a non-development dependency of the top level.

• optional:如果为真，则此依赖要么是仅顶层模块的可选依赖，要么是一个传递依赖。对于既是顶层的可选依赖又是顶层非可选依赖的传递依赖的依赖，这是错误的。

  ¥optional: If true then this dependency is either an optional dependency ONLY of the top level module or a transitive dependency of one. This is false for dependencies that are both an optional dependency of the top level and a transitive dependency of a non-optional dependency of the top level.

• requires:这是模块名称到版本的映射。这是这个模块需要的所有东西的列表，不管它安装在哪里。版本应该通过正常的匹配规则匹配我们 dependencies 或高于我们级别的依赖。

  ¥requires: This is a mapping of module name to version. This is a list of everything this module requires, regardless of where it will be installed. The version should match via normal matching rules a dependency either in our dependencies or in a level higher than us.

• dependencies:此依赖的依赖，与顶层完全一样。

  ¥dependencies: The dependencies of this dependency, exactly as at the top level.

也可以看看

¥See also

• npm shrinkwrap

• npm-shrinkwrap.json

• package.json

• npm install