PnP 规范
关于本文档
¥About this document
为了使第三方项目的互操作性更容易,本文档描述了我们在 Plug'n'Play 安装策略 下将文件安装到磁盘上时遵循的规范。这也意味着:
¥To make interoperability easier for third-party projects, this document describes the specification we follow when installing files on disk under the Plug'n'Play install strategy. It also means:
-
我们对本文档所做的任何更改都将遵循 semver 规则
¥any change we make to this document will follow semver rules
-
我们将尽力保持向后兼容性
¥we'll do our best to preserve backward compatibility
-
新功能将旨在优雅降级
¥new features will be intended to gracefully degrade
高级想法
¥High-level idea
Plug'n'Play 的工作原理是在内存中保存依赖树中所有包部分的表,这样我们就可以轻松回答两个不同的问题:
¥Plug'n'Play works by keeping in memory a table of all packages part of the dependency tree, in such a way that we can easily answer two different questions:
-
给定一个路径,它属于哪个包?
¥Given a path, what package does it belong to?
-
给定一个包,它可以访问的依赖在哪里?
¥Given a package, where are the dependencies it can access?
因此,解决包导入问题就变成了交织这两个操作的问题:
¥Resolving a package import thus becomes a matter of interlacing those two operations:
-
首先,找到哪个包正在请求解析
¥First, locate which package is requesting the resolution
-
然后检索其依赖,检查请求的包是否在其中
¥Then retrieve its dependencies, check if the requested package is amongst them
-
如果是,则检索依赖信息并返回其位置
¥If it is, then retrieve the dependency information, and return its location
然后可以设计额外的功能,但这些功能是可选的。例如,当无法解析依赖时,Yarn 利用其了解的有关项目的信息抛出语义错误:由于我们知道整个依赖树的状态,我们也知道包可能丢失的原因。
¥Extra features can then be designed, but are optional. For example, Yarn leverages the information it knows about the project to throw semantic errors when a dependency cannot be resolved: since we know the state of the whole dependency tree, we also know why a package may be missing.
基本概念
¥Basic concepts
所有包都由定位器唯一引用。定位器是包标识(如果相关,包括其范围)和包引用的组合,包引用可视为用于区分同一包的不同实例(或版本)的唯一 ID。包引用应被视为不透明值:从解析算法的角度来看,它们以 workspace:
、virtual:
、npm:
或任何其他协议开头并不重要。
¥All packages are uniquely referenced by locators. A locator is a combination of a package ident, which includes its scope if relevant, and a package reference, which can be seen as a unique ID used to distinguish different instances (or versions) of a same package. The package references should be treated as an opaque value: it doesn't matter from a resolution algorithm perspective that they start with workspace:
, virtual:
, npm:
, or any other protocol.
可移植性
¥Portability
出于可移植性原因,清单内的所有路径:
¥For portability reasons, all paths inside of the manifests:
-
必须使用 unix 路径格式(
/
作为分隔符)。¥must use the unix path format (
/
as separators). -
必须相对于清单文件夹(因此无论项目在磁盘上的位置如何,它们都是相同的)。
¥must be relative to the manifest folder (so they are the same regardless of the location of the project on disk).
本规范中的所有算法都假定路径已根据这两个规则进行了规范化。
¥All algorithms in this specification assume that paths have been normalized according to these two rules.
后备
¥Fallback
为了提高与旧代码库的兼容性,Plug'n'Play 支持我们称为 "fallback" 的功能。当包向其依赖中未列出的依赖触发解析请求时,会触发回退。在正常情况下,解析器会抛出错误,但是当启用回退时,解析器应该首先尝试在一组特殊包的依赖中找到依赖包。如果找到了,它会透明地返回它。
¥For improved compatibility with legacy codebases, Plug'n'Play supports a feature we call "fallback". The fallback triggers when a package makes a resolution request to a dependency it doesn't list in its dependencies. In normal circumstances the resolver would throw, but when the fallback is enabled the resolver should first try to find the dependency packages amongst the dependencies of a set of special packages. If it finds it, it then returns it transparently.
从某种意义上说,回退可以看作是一种有限且更安全的提升形式。虽然提升允许通过多个级别的依赖进行不受约束的访问,但回退需要明确定义回退包 - 通常是顶层的。
¥In a sense, the fallback can be seen as a limited and safer form of hoisting. While hoisting allows unconstrainted access through multiple levels of dependencies, the fallback requires to explicitly define a fallback package - usually the top-level one.
软件包位置
¥Package locations
虽然 Plug'n'Play 规范本身并不要求运行时在访问包文件时支持除常规文件系统之外的任何其他东西,但生产者可能依赖更复杂的数据存储机制。例如,Yarn 本身需要以下两个扩展,我们强烈建议支持它们:
¥While the Plug'n'Play specification doesn't by itself require runtimes to support anything else than the regular filesystem when accessing package files, producers may rely on more complex data storage mechanisms. For instance, Yarn itself requires the two following extensions which we strongly recommend to support:
Zip 访问
¥Zip access
为了访问文件,必须将名为 *.zip
的文件视为文件夹。例如,/foo/bar.zip/package.json
需要访问位 于 /foo/bar.zip
zip 存档中的 package.json
文件。
¥Files named *.zip
must be treated as folders for the purpose of file access. For instance, /foo/bar.zip/package.json
requires to access the package.json
file located within the /foo/bar.zip
zip archive.
如果编写 JS 工具,@yarnpkg/fslib
包可能会有所帮助,提供一个名为 ZipOpenFS
的 zip 感知文件系统层。
¥If writing a JS tool, the @yarnpkg/fslib
package may be of assistance, providing a zip-aware filesystem layer called ZipOpenFS
.
虚拟文件夹
¥Virtual folders
为了正确表示列出对等依赖的包,Yarn 依赖于一个名为 虚拟包 的概念。它们最显着的特性是它们都有不同的路径(以便 Node.js 可以根据需要多次实例化它们),同时仍然由磁盘上的同一个具体文件夹烘焙。
¥In order to properly represent packages listing peer dependencies, Yarn relies on a concept called Virtual Packages. Their most notable property is that they all have different paths (so that Node.js instantiates them as many times as needed), while still being baked by the same concrete folder on disk.
这是通过为以下方案添加路径支持来完成的:
¥This is done by adding path support for the following scheme:
/path/to/some/folder/__virtual__/<hash>/<n>/subpath/to/file.dat
当发现此模式时,必须删除 __virtual__/<hash>/<n>
部分,忽略 hash
,并将 dirname
操作应用于 /path/to/some/folder
部分 n
次。一些示例:
¥When this pattern is found, the __virtual__/<hash>/<n>
part must be removed, the hash
ignored, and the dirname
operation applied n
times to the /path/to/some/folder
part. Some examples:
/path/to/some/folder/__virtual__/a0b1c2d3/0/subpath/to/file.dat
/path/to/some/folder/subpath/to/file.dat
/path/to/some/folder/__virtual__/e4f5a0b1/0/subpath/to/file.dat
/path/to/some/folder/subpath/to/file.dat (different hash, same result)
/path/to/some/folder/__virtual__/a0b1c2d3/1/subpath/to/file.dat
/path/to/some/subpath/to/file.dat
/path/to/some/folder/__virtual__/a0b1c2d3/3/subpath/to/file.dat
/path/subpath/to/file.dat
如果编写 JS 工具,@yarnpkg/fslib
包可能会有所帮助,提供一个名为 VirtualFS
的虚拟感知文件系统层。
¥If writing a JS tool, the @yarnpkg/fslib
package may be of assistance, providing a virtual-aware filesystem layer called VirtualFS
.
__virtual__
文件夹名称出现在 Yarn 3.0 中。早期版本使用 $$virtual
,但我们在发现这种模式会触发软件中的错误后对其进行了更改,其中路径被用作正则表达式或替换。例如,在 String.prototype.replace
的第二个参数中找到的 $$
默默地变成了 $
。
¥The __virtual__
folder name appeared with Yarn 3.0. Earlier releases used $$virtual
, but we changed it after discovering that this pattern triggered bugs in software where paths were used as either regexps or replacement. For example, $$
found in the second parameter from String.prototype.replace
silently turned into $
.
清单参考
¥Manifest reference
当 pnpEnableInlining
明确设置为 false
时,Yarn 将生成一个包含以下字段的附加 .pnp.data.json
文件。
¥When pnpEnableInlining
is explicitly set to false
, Yarn will generate an additional .pnp.data.json
file containing the following fields.
本文档仅涵盖数据文件本身 - 你应该定义自己的内存数据结构,并在运行时使用清单中的信息进行填充。例如,Yarn 将 packageRegistryData
表变成两个单独的内存表:一个将路径映射到包,另一个将包映射到路径。
¥This document only covers the data file itself - you should define your own in-memory data structures, populated at runtime with the information from the manifest. For example, Yarn turns the packageRegistryData
table into two separate memory tables: one that maps a path to a package, and another that maps a package to a path.
你可能会注意到各个地方都使用元组数组代替映射。这主要是为了更容易地补充 ES6 映射,但有时也是为了拥有非字符串键(例如,在特定情况下 packageRegistryData
将具有 null
键)。
¥You may notice that various places use arrays of tuples in place of maps. This is mostly intended to make it easier to hydrate ES6 maps, but also sometimes to have non-string keys (for instance packageRegistryData
will have a null
key in one particular case).
__info
dependencyTreeRoots
ignorePatternData
enableTopLevelFallback
fallbackPool
fallbackExclusionList
packageRegistryData
packageRegistryData.packageLocation
packageRegistryData.packageDependencies
packageRegistryData.linkType
packageRegistryData.discardFromLookup
packageRegistryData.packagePeers
packageRegistryData.packageLocation
packageRegistryData.packageDependencies
packageRegistryData.linkType
packageRegistryData.discardFromLookup
packageRegistryData.packagePeers
解析算法
¥Resolution algorithm
NM_RESOLVE
NM_RESOLVE(specifier, parentURL)
-
该函数在 Node.js 文档 中指定
¥This function is specified in the Node.js documentation
PNP_RESOLVE
PNP_RESOLVE(specifier, parentURL)
-
让
resolved
为 undefined¥Let
resolved
be undefined -
如果
specifier
是 Node.js 内置函数,则¥If
specifier
is a Node.js builtin, then-
将
resolved
设置为specifier
本身并返回它¥Set
resolved
tospecifier
itself and return it
-
-
否则,如果
specifier
是绝对路径或以 "./" 或 "../" 为前缀的路径,则¥Otherwise, if
specifier
is either an absolute path or a path prefixed with "./" or "../", then-
将
resolved
设置为NM_RESOLVE
(specifier, parentURL)
并返回它¥Set
resolved
toNM_RESOLVE
(specifier, parentURL)
and return it
-
-
否则,
¥Otherwise,
-
注意:
specifier
现在是一个裸标识符¥Note:
specifier
is now a bare identifier -
让
unqualified
为RESOLVE_TO_UNQUALIFIED
(specifier, parentURL)
¥Let
unqualified
beRESOLVE_TO_UNQUALIFIED
(specifier, parentURL)
-
将
resolved
设置为NM_RESOLVE
(unqualified, parentURL)
¥Set
resolved
toNM_RESOLVE
(unqualified, parentURL)
-
RESOLVE_TO_UNQUALIFIED
RESOLVE_TO_UNQUALIFIED(specifier, parentURL)
-
让
resolved
为 undefined¥Let
resolved
be undefined -
让
ident
和modulePath
成为PARSE_BARE_IDENTIFIER
(specifier)
的结果¥Let
ident
andmodulePath
be the result ofPARSE_BARE_IDENTIFIER
(specifier)
-
让
manifest
为FIND_PNP_MANIFEST
(parentURL)
¥Let
manifest
beFIND_PNP_MANIFEST
(parentURL)
-
如果
manifest
为空,则¥If
manifest
is null, then-
将
resolved
设置为NM_RESOLVE
(specifier, parentURL)
并返回它¥Set
resolved
toNM_RESOLVE
(specifier, parentURL)
and return it
-
-
让
parentLocator
为FIND_LOCATOR
(manifest, parentURL)
¥Let
parentLocator
beFIND_LOCATOR
(manifest, parentURL)
-
如果
parentLocator
为空,则¥If
parentLocator
is null, then-
将
resolved
设置为NM_RESOLVE
(specifier, parentURL)
并返回它¥Set
resolved
toNM_RESOLVE
(specifier, parentURL)
and return it
-
-
让
parentPkg
为GET_PACKAGE
(manifest, parentLocator)
¥Let
parentPkg
beGET_PACKAGE
(manifest, parentLocator)
-
让
referenceOrAlias
成为ident
引用的来自parentPkg.packageDependencies
的条目¥Let
referenceOrAlias
be the entry fromparentPkg.packageDependencies
referenced byident
-
如果
referenceOrAlias
为空或未定义,则¥If
referenceOrAlias
is null or undefined, then-
如果
manifest.enableTopLevelFallback
为真,则¥If
manifest.enableTopLevelFallback
is true, then-
如果
parentLocator
不在manifest.fallbackExclusionList
中,则¥If
parentLocator
isn't inmanifest.fallbackExclusionList
, then-
让
fallback
为RESOLVE_VIA_FALLBACK
(manifest, ident)
¥Let
fallback
beRESOLVE_VIA_FALLBACK
(manifest, ident)
-
如果
fallback
既不为空也不为未定义¥If
fallback
is neither null nor undefined-
将
referenceOrAlias
设置为fallback
¥Set
referenceOrAlias
tofallback
-
-
-
-
-
如果
referenceOrAlias
仍未定义,则¥If
referenceOrAlias
is still undefined, then-
抛出解析错误
¥Throw a resolution error
-
-
如果
referenceOrAlias
仍为空,则¥If
referenceOrAlias
is still null, then-
注意:这意味着
parentPkg
对ident
具有未实现的对等依赖¥Note: It means that
parentPkg
has an unfulfilled peer dependency onident
-
抛出解析错误
¥Throw a resolution error
-
-
否则,如果
referenceOrAlias
是数组,则¥Otherwise, if
referenceOrAlias
is an array, then-
让
alias
为referenceOrAlias
¥Let
alias
bereferenceOrAlias
-
让
dependencyPkg
为GET_PACKAGE
(manifest, alias)
¥Let
dependencyPkg
beGET_PACKAGE
(manifest, alias)
-
返回
path.resolve(manifest.dirPath, dependencyPkg.packageLocation, modulePath)
¥Return
path.resolve(manifest.dirPath, dependencyPkg.packageLocation, modulePath)
-
-
否则,
¥Otherwise,
-
让
reference
为referenceOrAlias
¥Let
reference
bereferenceOrAlias
-
让
dependencyPkg
为GET_PACKAGE
(manifest, {ident, reference})
¥Let
dependencyPkg
beGET_PACKAGE
(manifest, {ident, reference})
-
返回
path.resolve(manifest.dirPath, dependencyPkg.packageLocation, modulePath)
¥Return
path.resolve(manifest.dirPath, dependencyPkg.packageLocation, modulePath)
-
GET_PACKAGE
GET_PACKAGE(manifest, locator)
-
让
referenceMap
成为locator.ident
引用的 来自parentPkg.packageRegistryData
的条目¥Let
referenceMap
be the entry fromparentPkg.packageRegistryData
referenced bylocator.ident
-
让
pkg
成为locator.reference
引用的来自referenceMap
的条目¥Let
pkg
be the entry fromreferenceMap
referenced bylocator.reference
-
返回
pkg
¥Return
pkg
FIND_LOCATOR
FIND_LOCATOR(manifest, moduleUrl)
此处描述的算法效率很低。阅读清单时,应确保准备更适合此任务的数据结构。
¥The algorithm described here is quite inefficient. You should make sure to prepare data structure more suited for this task when you read the manifest.
-
让
bestLength
为 0¥Let
bestLength
be 0 -
让
bestLocator
为 null¥Let
bestLocator
be null -
让
relativeUrl
成为manifest
和moduleUrl
之间的相对路径¥Let
relativeUrl
be the relative path betweenmanifest
andmoduleUrl
-
注意:相对路径不能以
./
开头;如果需要,请修剪它¥Note: The relative path must not start with
./
; trim it if needed
-
-
如果
relativeUrl
与manifest.ignorePatternData
匹配,则¥If
relativeUrl
matchesmanifest.ignorePatternData
, then-
返回 null
¥Return null
-
-
让
relativeUrlWithDot
成为relativeUrl
,并根据需要添加./
或../
作为前缀¥Let
relativeUrlWithDot
berelativeUrl
prefixed with./
or../
as necessary -
对于
manifest.packageRegistryData
中的每个referenceMap
值¥For each
referenceMap
value inmanifest.packageRegistryData
-
对于
referenceMap
中的每个registryPkg
值¥For each
registryPkg
value inreferenceMap
-
如果
registryPkg.discardFromLookup
不为真,则¥If
registryPkg.discardFromLookup
isn't true, then-
如果
registryPkg.packageLocation.length
大于bestLength
,则¥If
registryPkg.packageLocation.length
is greater thanbestLength
, then-
如果
relativeUrl
以registryPkg.packageLocation
开头,然后¥If
relativeUrl
starts withregistryPkg.packageLocation
, then-
将
bestLength
设置为registryPkg.packageLocation.length
¥Set
bestLength
toregistryPkg.packageLocation.length
-
将
bestLocator
设置为当前registryPkg
定位器¥Set
bestLocator
to the currentregistryPkg
locator
-
-
-
-
-
-
返回
bestLocator
¥Return
bestLocator
RESOLVE_VIA_FALLBACK
RESOLVE_VIA_FALLBACK(manifest, ident)
-
让
topLevelPkg
为GET_PACKAGE
(manifest, {null, null})
¥Let
topLevelPkg
beGET_PACKAGE
(manifest, {null, null})
-
让
referenceOrAlias
成为ident
引用的来自topLevelPkg.packageDependencies
的条目¥Let
referenceOrAlias
be the entry fromtopLevelPkg.packageDependencies
referenced byident
-
如果
referenceOrAlias
已定义,则¥If
referenceOrAlias
is defined, then-
立即返回
¥Return it immediately
-
-
否则,
¥Otherwise,
-
让
referenceOrAlias
成为ident
引用的来自manifest.fallbackPool
的条目¥Let
referenceOrAlias
be the entry frommanifest.fallbackPool
referenced byident
-
无论是否定义,都立即返回
¥Return it immediately, whether it's defined or not
-
FIND_PNP_MANIFEST
FIND_PNP_MANIFEST(url)
找到用于解析的正确 PnP 清单并不总是那么容易。主要有两个选项:
¥Finding the right PnP manifest to use for a resolution isn't always trivial. There are two main options:
-
假设有一个 PnP 清单涵盖整个项目。这是最常见的情况,因为即使引用第三方项目(例如通过
portal:
协议),它们的依赖树也存储在与主项目相同的清单中。¥Assume that there is a single PnP manifest covering the whole project. This is the most common case, as even when referencing third-party projects (for example via the
portal:
protocol) their dependency trees are stored in the same manifest as the main project.为此,请在进程开始时调用一次
FIND_CLOSEST_PNP_MANIFEST
(require.main.filename)
,缓存其结果,并在每次调用FIND_PNP_MANIFEST
时返回它(如果你在 Node.js 中运行,你甚至可以使用require.resolve('pnpapi')
为你完成这项工作)。¥To do that, call
FIND_CLOSEST_PNP_MANIFEST
(require.main.filename)
once at the start of the process, cache its result, and return it for each call toFIND_PNP_MANIFEST
(if you're running in Node.js, you can even userequire.resolve('pnpapi')
which will do this work for you). -
尝试在多项目世界中操作。这很少需要。我们在 Node.js PnP 加载器中支持它,但仅仅是因为 "项目生成器" 工具(如
create-react-app
)通过yarn create react-app
运行,并且需要两个不同的项目(生成器and
生成的项目)在同一个 Node.js 进程中协作。¥Try to operate within a multi-project world. This is rarely required. We support it inside the Node.js PnP loader, but only because of "project generator" tools like
create-react-app
which are run viayarn create react-app
and require two different projects (the generator oneand
the generated one) to cooperate within the same Node.js process.支持此用例很困难,因为它需要一个簿记机制来跟踪用于访问模块的清单,尽可能多地重用它们,并且仅在链中断时寻找新的清单。
¥Supporting this use case is difficult, as it requires a bookkeeping mechanism to track the manifests used to access modules, reusing them as much as possible and only looking for a new one when the chain breaks.
FIND_CLOSEST_PNP_MANIFEST
FIND_CLOSEST_PNP_MANIFEST(url)
-
让
manifest
为 null¥Let
manifest
be null -
让
directoryPath
成为url
的目录¥Let
directoryPath
be the directory forurl
-
让
pnpPath
成为directoryPath
与/.pnp.cjs
连接¥Let
pnpPath
bedirectoryPath
concatenated with/.pnp.cjs
-
如果
pnpPath
存在于文件系统中,则¥If
pnpPath
exists on the filesystem, then-
让
pnpDataPath
成为directoryPath
与/.pnp.data.json
连接¥Let
pnpDataPath
bedirectoryPath
concatenated with/.pnp.data.json
-
将
manifest
设置为JSON.parse(readFile(pnpDataPath))
¥Set
manifest
toJSON.parse(readFile(pnpDataPath))
-
将
manifest.dirPath
设置为directoryPath
¥Set
manifest.dirPath
todirectoryPath
-
返回
manifest
¥Return
manifest
-
-
否则,如果
directoryPath
是/
,则¥Otherwise, if
directoryPath
is/
, then-
返回 null
¥Return null
-
-
否则,
¥Otherwise,
-
返回
FIND_PNP_MANIFEST
(directoryPath)
¥Return
FIND_PNP_MANIFEST
(directoryPath)
-
PARSE_BARE_IDENTIFIER
PARSE_BARE_IDENTIFIER(specifier)
-
如果
specifier
以 "@" 开头,然后¥If
specifier
starts with "@", then-
如果
specifier
不包含 "/" 分隔符,则¥If
specifier
doesn't contain a "/" separator, then-
抛出错误
¥Throw an error
-
-
否则,
¥Otherwise,
-
将
ident
设置为specifier
的子字符串,直到第二个 "/" 分隔符或字符串的末尾,以先发生者为准¥Set
ident
to the substring ofspecifier
until the second "/" separator or the end of string, whatever happens first
-
-
-
否则,
¥Otherwise,
-
将
ident
设置为specifier
的子字符串,直到第一个 "/" 分隔符或字符串的末尾,以先发生者为准¥Set
ident
to the substring ofspecifier
until the first "/" separator or the end of string, whatever happens first
-
-
将
modulePath
设置为从ident.length
开始的specifier
的子字符串¥Set
modulePath
to the substring ofspecifier
starting fromident.length
-
返回
{ident, modulePath}
¥Return
{ident, modulePath}