pnpm 作为一个优秀的包管理工具,在如今的前端生态中呈持续发展的趋势,与 npm、yarn 相比,它在底层上做了彻底性的改变,通过软硬链接、并行处理依赖等方式实现了更快更省空间的依赖管理,有效解决了幽灵依赖的问题。
作为程序员,我们不能仅仅把目光聚焦于工具的使用上,而是要有意识地去了解工具的实现原理。这篇文章就会给大家带来 pnpm 的源码结构探究!
对于 pnpm 在应用和优势上的探究,可以阅读文章:
面试官:说说包管理工具的发展以及 pnpm 依赖治理的最佳实践 🤯 - 掘金 (juejin.cn)
其他源码阅读文章:
基于源码的 Webpack 结构分析 - 掘金 (juejin.cn)
首先我们来观察一个总览的执行过程,大概看一下 pnpm 会做些什么:
处理命令
用户在终端执行命令之后,会进入 pnpm/src/main.ts 进行命令解析,具体逻辑如下:
1async function main(inputArgv: string[]) {
2
3 let parsedCliArgs = await parseCliArgs(inputArgv);
4
5 const { cmd, unknownOptions, workspaceDir } = parsedCliArgs;
6
7
8
9
10 let config: Config & {
11 forceSharedLockfile: boolean
12 argv: { remain: string[], cooked: string[], original: string[] }
13 fallbackCommandUsed: boolean
14 }
15
16 const globalDirShouldAllowWrite = cmd !== 'root'
17 config = await getConfig(cliOptions, {
18 excludeReporter: false,
19 globalDirShouldAllowWrite,
20
21 }) as typeof config
22
23 if (cmd) {
24 config.extraEnv = {
25 ...config.extraEnv,
26
27 npm_command: cmd === 'run' ? 'run-script' : cmd,
28 }
29 }
30
31
32
33
34
35 let { output, exitCode }: { output?: string | null, exitCode: number } =
36 await (async () => {
37 let result = pnpmCmds[cmd ?? 'help'](
38 config as Omit<typeof config, 'reporter'>,
39 cliParams
40 )
41 if (result instanceof Promise) result = await result
42
43 return result
44 })();
45
46
47 if (output) console.log(output);
48
49 if (exitCode) process.exitCode = exitCode;
50}
可以看到最终执行在 pnpmCmds
中进行,对于 pnpmCmds
的具体实现,我们放在后续进行介绍。可以看到 main.ts 作为入口函数,执行了从获取命令、处理并得到最终 config 、pnpm 更新、处理过滤行为,再到执行、输出等任务,涵盖了 pnpm 的全流程,在进一步了解具体的命令执行前,我们可以依据 main 的执行顺序依次分析源码中的一些 case。
执行自定义脚本
我们常在项目的 package.json 中定义 scripts
脚本,比如我们执行 pnpm run dev
,pnpm 内部会检测到 dev 是一个特殊命令,并执行相关的命令。
1if (cmd) {
2 config.extraEnv = {
3 ...config.extraEnv,
4
5
6 npm_command: cmd === 'run' ? 'run-script' : cmd,
7 }
8}
但我们平时单纯执行 pnpm dev
也可以触发脚本,这是为什么呢?
我们可以在 script 中注册一个 add 命令,并分别执行 pnpm run add
和 pnpm add
并查看结果:
可以看到 pnpm add
指向的是 pnpm 中默认的 add 命令而非 script 中注册的 add。
那么可以得到以下结论:
- 如果注册的命令与 pnpm 中默认的命令没有重复,则执行
pnpm <command>
时,会默认执行 script 中注册的命令(如果命中)。 - 如果有重复,优先执行 pnpm 中默认的命令。
pnpm 更新
pnpm 的版本更新分为两种:自更新、检查更新
自更新
在 main.ts 中,会通过判断命令中是否为 add、update,且是否在参数中含有 pnpm 来决定是否进行自更新。此时如果判断需要执行,那么会先通过 pnpmCmds.server(config as any, ['stop'])
来关闭可能正在执行的 pnpm 命令,防止出现冲突或使用问题。
1
2 const selfUpdate = config.global && (cmd === 'add' || cmd === 'update') && cliParams.includes(packageManager.name)
3
4 if (selfUpdate) {
5 await pnpmCmds.server(config as any, ['stop'])
6 const currentPnpmDir = path.dirname(which.sync('pnpm'))
7 if (path.relative(currentPnpmDir, config.bin) !== '') {
8 console.log(`The location of the currently running pnpm differs from the location where pnpm will be installed
9 Current pnpm location: ${currentPnpmDir}
10 Target location: ${config.bin}
11 `)
12 }
13 }
检查更新
pnpm 还会在一定判断条件下执行 checkForUpdates
,来检测是否需要更新。
1if (
2 config.updateNotifier !== false &&
3 !isCI &&
4 !selfUpdate &&
5 !config.offline &&
6 !config.preferOffline &&
7 !config.fallbackCommandUsed &&
8 (cmd === 'install' || cmd === 'add')
9) {
10 checkForUpdates(config).catch(() => { })
11}
可以看到为了防止和 selfUpdate 冲突导致进行无效检测,这边加了一个 !selfUpdate
的判断。接下来我们看看
checkForUpdates
的内容吧:
1export async function checkForUpdates(config: Config) {
2
3 const stateFile = path.join(config.stateDir, 'pnpm-state.json');
4 let state = await loadJsonFile(stateFile);
5
6
7 if (
8 state?.lastUpdateCheck &&
9 (Date.now() - new Date(state.lastUpdateCheck).valueOf()) < UPDATE_CHECK_FREQUENCY
10 ) return;
11
12
13 const resolve = createResolver({
14 ...config,
15 authConfig: config.rawConfig,
16 retry: {
17 retries: 0,
18 },
19 });
20
21
22 const resolution = await resolve({ alias: packageManager.name, pref: 'latest' }, {
23 lockfileDir: config.lockfileDir ?? config.dir,
24 preferredVersions: {},
25 projectDir: config.dir,
26 registry: pickRegistryForPackage(config.registries, packageManager.name, 'latest'),
27 });
28
29
30 if (resolution?.manifest?.version) {
31 updateCheckLogger.debug({
32 currentVersion: packageManager.version,
33 latestVersion: resolution?.manifest.version,
34 });
35 }
36
37
38}
可以看到函数仅仅是做了状态更新的检查并进行提示,并没有直接进行更新操作。
过滤操作
在 pnpm 中,filter 是一种非常重要的功能,用于指定对哪些项目或包应用命令。在 monorepo 中的用户来说尤为有用,因为它允许用户精确控制每个命令的作用范围。
1# e.g.
2pnpm --filter "{.}" add eslint@latest -D
在了解 filter 操作前,我们先了解一下工作区(workspace)的定义: 工作区是一个包含多个包的容器,这些包可以共享依赖、配置和任务。开发者可以同时在多个相关的项目上工作,而不需要每次都重新配置每个项目或手动处理依赖关系。其中,pnpm 通过 pnpm-workspace.yaml
文件来进行工作区的管理。
filter 的操作就是基于 workspace 进行的,我们看看筛选是如何实现的吧:
1
2if (
3 (cmd === 'install' || cmd === 'import' || cmd === 'dedupe' || cmd === 'patch-commit' || cmd === 'patch') &&
4 typeof workspaceDir === 'string'
5) {
6 cliOptions['recursive'] = true;
7 config.recursive = true;
8
9
10 if (!config.recursiveInstall && !config.filter && !config.filterProd) {
11 config.filter = ['{.}...'];
12 }
13}
14
15if (cliOptions['recursive']) {
16
17 const wsDir = workspaceDir ?? process.cwd();
18
19
20 const filters = [
21 ...config.filter.map((filter) => ({ filter, followProdDepsOnly: false })),
22 ...config.filterProd.map((filter) => ({ filter, followProdDepsOnly: true })),
23 ];
24
25
26 const relativeWSDirPath = () => path.relative(process.cwd(), wsDir) || '.';
27
28
29 if (config.workspaceRoot) {
30 filters.push({ filter: `{${relativeWSDirPath()}}`, followProdDepsOnly: Boolean(config.filterProd.length) });
31 } else if (!config.includeWorkspaceRoot && (cmd === 'run' || cmd === 'exec' || cmd === 'add' || cmd === 'test')) {
32 filters.push({ filter: `!{${relativeWSDirPath()}}`, followProdDepsOnly: Boolean(config.filterProd.length) });
33 }
34
35
36 const filterResults = await filterPackagesFromDir(wsDir, filters, {
37
38 });
39
40
41 config.allProjectsGraph = filterResults.allProjectsGraph;
42 config.selectedProjectsGraph = filterResults.selectedProjectsGraph;
43
44
45 config.allProjects = filterResults.allProjects;
46 config.workspaceDir = wsDir;
47}
可以看到,filters 中记录了不同的筛选匹配规则,最终得到筛选结果 filterResults
,提取出所有需要处理的项目。
执行命令
接下来我们看看 pnpmCmds
中的具体实现吧!直接上源码:
1
2export interface CommandDefinition {
3 handler: Command;
4 help: () => string;
5 commandNames: string[];
6 completion?: CompletionFunc;
7
8};
9
10
11const commands: CommandDefinition[] = [
12 add, audit, bin, ci, config, dedupe, getCommand, setCommand, create, deploy, dlx,
13 doctor, env, exec, fetch, importCommand, init, install, installTest, link, list,
14 ll, licenses, outdated, pack, patch, patchCommit, prune, publish, rebuild, recursive,
15 remove, restart, root, run, server, setup, store, test, unlink, update, why,
16];
17
18
19const handlerByCommandName: Record<string, Command> = {};
20
21
22for (const cmdDef of commands) {
23 const { commandNames, handler, } = cmdDef;
24 for (const name of commandNames) {
25 handlerByCommandName[name] = handler;
26 }
27}
28
29
30handlerByCommandName.help = createHelp(helpByCommandName);
31handlerByCommandName.completion = createCompletion({xxx});
32
33
34export const pnpmCmds = handlerByCommandName;
可以看到 pnpmCmds 是一个命令执行对象,其中存放了 commands 中相关命令的 handler 函数,在 main.ts 中调用:
1let result = pnpmCmds[cmd ?? 'help'](
2 config
3 cliParams
4)
这一步再往后,会因为执行命令的不同而触发各自的 handler 函数,我们可以将所有的命令进行分类,然后在每个类中挑选几个重要的进行解析。首先我们基于 command 内容进行分类:
-
包安装与管理
add
: 添加新的包依赖。install
(aliasi
): 安装所有依赖。ci
: 类似npm ci
,用于持续集成环境中快速且可靠地安装依赖。update
(aliasup
): 更新依赖包。unlink
: 解除包链接。link
: 链接本地包。prune
: 清除未列在包依赖中的包。remove
(aliasrm
,uninstall
,r
): 移除依赖包。
-
工作区和多包管理
recursive
: 递归执行命令。exec
: 在每个包中执行任意命令。run
: 在包中运行定义在package.json
的脚本命令。
-
包信息查询与分析
list
(aliasls
): 列出已安装的包。outdated
: 检查过时的包。why
: 解释为什么包被安装。licenses
: 列出项目依赖的许可信息。
-
配置与环境管理
config
: 管理 pnpm 配置。getCommand
: 获取配置的值。setCommand
: 设置配置的值。env
: 管理环境变量。
-
发布与版本管理
publish
: 发布包到注册中心。pack
: 打包成 tarball。
-
特殊用途命令
audit
: 审计依赖以检测安全漏洞。bin
: 显示二进制文件的安装位置。doctor
: 检查 pnpm 配置和依赖健康状况。fetch
: 预下载依赖而不安装。importCommand
: 从 npm 或 yarn 的 lock 文件导入生成pnpm-lock.yaml
。init
: 创建一个新的package.json
文件。rebuild
: 重建依赖。server
: 管理一个或多个 pnpm 服务器。setup
: 设置 pnpm 的环境。
-
开发辅助命令
create
: 快速启动新项目的生成器。dlx
: 在没有全局安装的情况下临时运行命令。patch
: 创建和应用补丁。patchCommit
: 提交补丁。
-
.pnpm-store 管理命令
store
: 管理 .pnpm-store(存储所有 pnpm 包的地方)。
-
维护与其他命令
dedupe
: 精简冗余包。deploy
: 部署命令,可能特定于某些系统。
具体命令分析
在了解具体命令实现之前,我们可以先了解一个命令的结构设计。可以发现,命令的类型已经被定义好了:
1export interface CommandDefinition {
2 handler: Command
3 help: () => string
4 commandNames: string[]
5 cliOptionsTypes: () => Record<string, unknown>
6 rcOptionsTypes: () => Record<string, unknown>
7 completion?: CompletionFunc
8 shorthands?: Record<string, string | string[]>
9}
这个接口定义了 pnpm 命令的核心结构和元数据,我们来看看每个属性的具体作用:
handler
:命令的主逻辑处理函数,当命令被调用时执行。help
:提供命令的帮助文本,描述命令的用途、用法和可用选项,当执行帮助命令时被调用(pnpm help <command>
)。
commandNames
:存放命令标识符,可以在命令行中输入来调用。第一个名称通常是主命令名,其他的可能是简写或别名。cliOptionsTypes
:返回一个对象,键是此命令接受的命令行接口(CLI)选项,值是这些选项的值的类型,用于验证用户输入的选项值是否符合规范。
1export function cliOptionsTypes() {
2 return {
3 'save-dev': Boolean,
4 'fetch-retries': Number,
5 'custom-option': String
6 };
7}
8
9
10
rcOptionsTypes
:与cliOptionsTypes
同样的数据结构和作用,最后会被传入cliOptionsTypes
,
用于定义 .npmrc
或 .pnpmrc
配置文件中可以设置的选项的类型。
-
区别:
cliOptionsTypes
主要影响单次命令行会话,而rcOptionsTypes
影响所有命令的执行环境和行为。两者虽然可能涉及同样的设置项,但应用层面和影响范围有所不同。 -
completion
:可选,用户输入命令时监听 Tab 键,提供自动补全。 -
shorthands
:可选,定义命令选项的简写形式,例如,-D
可以代表--save-dev
。可以发现shorthands
与 help 中的 shortALias 存在一定耦合,这个问题可以在后面仔细探究。
我们在了解一个具体命令实现的时候,可以通过观察 helper 了解具体的使用方式,通过观察 handler 了解具体的执行逻辑,为控制篇幅,下面仅介绍一下 pnpm 的一个核心内容:包的安装与更新。
触发执行与执行类型
这个操作涉及到 pnpm add/update/install 等命令,由于核心的执行函数是一致的,我们放在一起去讲述。
以 pnpm add 开头,该命令主要用于将新的包添加到项目中,会自动更新 package.json
文件,将新包添加到依赖列表中,并且安装该包及其依赖。
1
2export async function handler(opts: AddCommandOptions, params: string[]) {
3
4
5
6
7 return installDeps({
8 ...opts,
9 include,
10 includeDirect: include,
11 }, params);
12}
installDeps
就是这几个命令共同的核心逻辑,我们可以来看看 installDeps
的实现,这里的实现逻辑相方复杂,我们可以先通过结构图来了解函数所执行的功能:
根据三个判断进行拆分,可以得到四个处理部分,我们分别来进行介绍:
第一部分:当前在工作区且存在内部依赖关系
1
2if (opts.workspaceDir) {
3 const selectedProjectsGraph = opts.selectedProjectsGraph ?? selectProjectByDir(allProjects, opts.dir);
4
5 if (selectedProjectsGraph != null) {
6
7
8
9
10 await recursive(allProjects, params, { ...opts, xxx },
11
12 opts.update ? 'update' : (params.length === 0 ? 'install' : 'add')
13 );
14
15 return;
16 }
17}
18
19function selectProjectByDir (projects: Project[], searchedDir: string) {
20 const project = projects.find(({ dir }) => path.relative(dir, searchedDir) === '')
21 if (project == null) return undefined
22 return { [searchedDir]: { dependencies: [], package: project } }
23}
selectProjectByDir
会分析工作区中项目的依赖关系,返回一个项目依赖图,如果存在项目内依赖,则会递归执行安装、更新或添加依赖,然后直接结束流程。
第二部分:没有内部依赖关系(monorepo 或单项目),指定了 params 依赖
1
2let { manifest, writeProjectManifest } = await tryReadProjectManifest(opts.dir, opts);
3
4
5const store = await createOrConnectStoreController(opts);
6
7const installOpts = {
8 ...opts,
9 ...getOptionsFromRootManifest(manifest),
10
11};
12
13let updateMatch = null;
14
15if (opts.update) updateMatch = params.length ? createMatcher(params) : null;
16
17
18
19if (params?.length) {
20
21 const mutatedProject = {
22 dependencySelectors: params,
23 manifest,
24 rootDir: opts.dir,
25
26 }
27
28 const updatedImporter = await mutateModulesInSingleProject(mutatedProject, installOpts)
29
30 await writeProjectManifest(updatedImporter.manifest)
31 return
32}
可以看到,在第二部分执行之前,有创建或连接 .pnpm-store 的行为,可以优化 pnpm 依赖的安装速度。
第二部分会判断在命令传入的 params 中是否有指定依赖,如:
1pnpm install lodash@latest
如果 params 有值,就会执行 mutateModulesInSingleProject
,更新指定依赖,并直接结束流程。
第三部分:没有内部依赖关系(monorepo 或单项目),没有指定 params 依赖
1const updatedManifest = await install(manifest, installOpts)
2
3if (opts.update === true) {
4 await writeProjectManifest(updatedManifest)
5}
如果 params 没有值,那么就会执行默认的全项目安装。
第四部分:配置了在工作区环境中链接包(linkWorkspacePackages),并且指定了工作区目录
1
2if (opts.linkWorkspacePackages && opts.workspaceDir) {
3
4 const { selectedProjectsGraph } = await filterPkgsBySelectorObjects(allProjects, [{ xxx }], {
5 workspaceDir: opts.workspaceDir,
6 })
7
8 await recursive(allProjects, [], {
9 ...opts,
10 ...OVERWRITE_UPDATE_OPTIONS,
11 allProjectsGraph: opts.allProjectsGraph!,
12 selectedProjectsGraph,
13 workspaceDir: opts.workspaceDir,
14 }, 'install')
15
16
17 if (opts.ignoreScripts) return
18
19
20 await rebuildProjects(xxx)
21}
可以看到 1、4 两个部分逻辑十分相似,这边就需要研究一下 linkWorkspacePackages
和 workspcae 配置项目依赖的关系了。
可以看到 linkWorkspacePackages
的配置功能如下:
-
true(默认) :如果在同一工作区中存在包间的依赖关系,这些依赖会通过创建符号链接(symlinks)直接链接到依赖的本地包,而不是从外部 npm 注册表下载。
-
deep:不仅顶层的直接依赖会链接到工作区中的其他包,所有依赖(包括深层依赖)也会尽可能链接到工作区中的包。
-
false:禁用了工作区包的自动链接功能。即使包在工作区中可用,也会从 npm 注册表下载这些包。
可以看到当允许工作区项目间创建符号链接时,会触发安装。我们再看第一、四部分在 recursive
中的差异。第一部分传入的方法可以是 install、add、update,第四部分只能传入 install,由此可以总结:
触发到第四部分的条件为:
- 在工作区且项目之间没有互相依赖。
linkWorkspacePackages
为 true/deep。- 执行的命令为
pnpm install
。
那么这一部份会逐个安装每个 importer(子项目),确保项目的正常运行。
了解清楚了 installDeps
的执行逻辑,我们再来整理一个基于四个执行部分的流程图:
具体执行逻辑
上一部分的核心逻辑还是依据执行的环境选择执行的方式,具体如何实现还需要关注相关的函数,可以看到有:recursive
、mutateModulesInSingleProject
,以及 install
,通过观察三个函数的代码,发现都存在一个核心函数 mutateModules
,此外都是一些参数的处理操作,因此我们可以直接来研究 mutateModules
的实现。
1export async function mutateModules(projects: MutatedProject[], maybeOpts: MutateModulesOptions): Promise<UpdatedProject[]> {
2
3 const opts = await extendOptions(maybeOpts);
4
5 const installsOnly = projects.every((project) => project.mutation === 'install' && !project.update && !project.updateMatching);
6 opts['forceNewModules'] = installsOnly;
7
8
9 const ctx = await getContext(opts);
10
11 if (opts.hooks.preResolution) {
12 await opts.hooks.preResolution({ xxx });
13 }
14
15
16 return await _install();
17
18
19 async function _install(): Promise<UpdatedProject[]> {
20
21
22 const projectsToInstall = [] as ImporterToUpdate[]
23 for (const project of projects) {
24 switch (project.mutation) {
25 case 'uninstallSome':
26 projectsToInstall.push({ xxx })
27 break
28 case 'install': {
29 await installCase({ xxx })
30 break
31 }
32 case 'installSome': {
33 await installSome({ xxx })
34 break
35 }
36 case 'unlink': {
37 await installCase({ xxx })
38 break
39 }
40 case 'unlinkSome': {
41 await installSome({ xxx })
42 break
43 }
44 }
45 }
46
47
48 async function installCase(project: any) { }
49
50 async function installSome(project: any) { }
51
52 const result = await installInContext(projectsToInstall, ctx, { xxx })
53 return result.projects
54 }
55}
56
57const installInContext: InstallFunction = async (projects, ctx, opts) => {
58
59
60 await Promise.all(projects.map(async (project) => {
61 if (project.mutation !== 'uninstallSome') return
62 const _removeDeps = async (manifest: ProjectManifest) => removeDeps(manifest, project.dependencyNames, { prefix: project.rootDir, saveType: project.targetDependenciesField })
63 project.manifest = await _removeDeps(project.manifest)
64 if (project.originalManifest != null) {
65 project.originalManifest = await _removeDeps(project.originalManifest)
66 }
67 })
68 )
69
70
71 let { dependenciesGraph, dependenciesByProjectId, xxx } = await resolveDependencies(xxx)
72
73 if (!opts.lockfileOnly && !isInstallationOnlyForLockfileCheck && opts.enableModulesDir) {
74
75 const result = await linkPackages(xxx)
76
77 await finishLockfileUpdates()
78
79 }
80
81
82 await Promise.all([ xxx ]);
83
84 await opts.storeController.close();
85
86 reportPeerDependencyIssues(xxx)
87 return { xxx }
88}
尽管经过大量压缩,还是有很多的代码量。
我们可以看到在 projects 的遍历中,switch 语句根据不同的 project.mutation
值,决定了对于每个项目应该采取的操作,其中每个 case
都对应了一种特定的操作模式:
-
uninstallSome
- 功能:移除指定的依赖包。
- 操作:从项目的依赖清单中移除指定的依赖名称(
project.dependencyNames
)。
-
install
- 功能:安装项目的所有依赖。
- 操作:调用
installCase
函数,处理安装操作。
-
installSome
- 功能:安装或更新项目的特定依赖。
- 操作:调用
installSome
函数,指定需要处理的依赖项。这通常是用于添加新依赖或更新现有依赖。
-
unlink
-
功能:解除链接已安装的包。
-
操作:
- 首先读取项目的
modules
目录来确定哪些包是外部链接。 - 通过
pFilter
函数确定哪些包实际上是从外部链接的(而非本地安装的)。 - 从
modules
目录中移除这些外部链接的包。 - 如果包在项目的依赖定义中,将这些包加入重新安装列表。
- 首先读取项目的
-
-
unlinkSome
-
功能:解除特定依赖包的链接。
-
操作:
- 对于每个指定的依赖名称,检查它是否为外部链接。
- 如果是外部链接,则从
modules
目录中移除。 - 不会自动在
package.json
中更新版本规范,而是重新安装这些包。
-
这样的设计保证了不同的执行命令调用函数时,触发各种各样的结果,我们拿 pnpm add jest -w
举例,下面是执行的流程:
其中还有很多细节值得研究,如 .pnpm-store 与项目的交互、pnpm 的生命周期钩子、软硬链接的具体实现等,后续可以作为独立模块进行分享。
相较于其他开源库,在阅读 pnpm 源码的过程中,明显能感觉到学习难度涨幅很大,一开始 main
的结构十分清晰简单,当深入到 installDeps
时,整体的代码量开始越来越夸张,且具有一定跳跃性,需要结合 debugger 和 gpt,以及大量的时间进行分析,逐渐锁定核心的执行过程,如此反复……好不容易整理清楚全流程后,却发现这仅仅是 pnpm 众多执行命令中的冰山一角😰。
然而源码的阅读就是如此,想要成为 pnpm 的专家,必然付出大量的时间进行研究。
最后总结一下,这篇文章介绍了 pnpm 的架构设计和执行逻辑,涉及到具体的命令仅有包的安装与更新这一块,后续的更新会更专注于细节问题的实现和分析上,如果本文有任何问题,欢迎评论指出,感谢!