依赖项解析

相关源文件

• src/bun.zig
• src/cli/pm_trusted_command.zig
• src/deps/diffz/DiffMatchPatch.zig
• src/install/bin.zig
• src/install/dependency.zig
• src/install/extract_tarball.zig
• src/install/install.zig
• src/install/lockfile.zig
• src/install/migration.zig
• src/install/npm.zig
• src/install/repository.zig
• src/install/resolution.zig
• test/cli/install/__snapshots__/bun-workspaces.test.ts.snap
• test/cli/install/__snapshots__/semver.test.ts.snap
• test/cli/install/bun-add.test.ts
• test/cli/install/bun-install.test.ts
• test/cli/install/bun-link.test.ts
• test/cli/install/bun-remove.test.ts
• test/cli/install/bun-update.test.ts
• test/cli/install/bun-workspaces.test.ts
• test/cli/install/semver-fixture.js
• test/cli/install/semver.test.ts
• test/harness.ts
• test/regression/issue/08040.test.ts

本文档介绍了 Bun 的依赖解析系统，该系统将 package.json 文件中指定的包依赖项转换为具体的包版本和源。该系统处理 NPM 包、Git 仓库、本地文件和 tarball 等各种依赖类型，并将它们解析为一致的锁定文件格式。

有关解析后包安装过程的信息，请参阅 安装过程。有关锁定文件格式的详细信息，请参阅 锁定文件系统。

概述

Bun 的依赖解析通过一个多阶段管道运行，该管道处理依赖项规范，查询包注册表，应用版本约束，并生成已解析的包标识符。该系统支持多种包源，并处理具有工作区支持的复杂依赖关系图。

核心解析管道

依赖解析流程

来源: src/install/install.zig1-100 src/install/dependency.zig1-50 src/install/resolution.zig1-30

依赖类型和解析

解析系统首先将 package.json 中的依赖项规范解析为结构化的 Dependency 对象。每个依赖项包含名称、版本约束以及指示其源类型的行为标志。

依赖类型分类

Dependency.Version 结构使用带标签的联合来表示不同的版本类型

类型	格式	示例
npm	Semver 范围	^1.2.3, ~2.0.0
git	Git URL	git+https://github.com/user/repo.git
github	GitHub 简写	user/repo#branch
folder	本地路径	file:../local-package
tarball	Tarball URL	https://example.com/package.tgz
dist_tag	Tag 引用	latest, beta

来源: src/install/dependency.zig322-400 src/install/dependency.zig168-295

注册表解析

对于 NPM 依赖项，解析系统会查询包注册表以获取元数据并确定可用版本。此过程使用 NetworkTask 系统进行并发 HTTP 请求。

NPM 注册表解析过程

PackageManager 维护一个 NetworkTask 实例池，以高效处理并发注册表请求。每个任务都包含重试逻辑和作用域包的身份验证处理。

来源: src/install/install.zig242-278 src/install/npm.zig275-400 src/install/install.zig315-470

版本约束满足

版本解析算法使用 semver 匹配来查找满足依赖项约束的最佳可用版本。这包括解析版本范围并将其与可用包版本进行比较。

版本匹配算法

该系统实现了兼容 NPM 的 semver 解析，包括对以下内容的 I支持：

• Caret 范围 (^1.2.3) - 兼容版本
• Tilde 范围 (~1.2.3) - 补丁级别更改
• 精确版本 (1.2.3) - 特定版本
• 预发行版本 (1.2.3-alpha.1)
• 构建元数据 (1.2.3+build.1)

来源: src/install/dependency.zig318-320 src/bun.zig601-650

Git 仓库解析

Git 依赖项经过专门的解析过程，该过程会克隆仓库并将提交引用解析为特定的 SHA。

Git 解析工作流

Repository 模块处理各种 Git URL 格式，并在可能的情况下执行浅克隆以优化性能。它支持 HTTPS 和 SSH 协议，并处理凭据。

来源: src/install/repository.zig132-200 src/install/dependency.zig168-190

工作区解析

Bun 支持 monorepo 工作区，其中依赖项可以解析为本地工作区包，而不是外部注册表包。

工作区解析优先级

解析器首先检查工作区包，然后回退到外部注册表。这使得工作区包在满足版本约束时可以覆盖外部依赖项。

来源: src/install/lockfile.zig529-577 src/install/lockfile.zig655-713

解析存储

解析后的依赖项存储在锁定文件中，作为 Resolution 对象，该对象引用特定的包版本和源。锁定文件维护依赖项 ID 和包 ID 之间的映射。

解析存储结构

锁定文件使用高效存储，并进行字符串驻留和引用以最大限度地减少内存使用。包去重可确保相同的包无论有多少依赖项引用它们，都只存储一次。

字段	类型	目的
tag	Resolution.Tag	解析类型标识符
value	Resolution.Value	特定于类型的解析数据
package_id	PackageID	对包元数据的引用

来源: src/install/resolution.zig12-25 src/install/lockfile.zig8-30

并发解析

依赖解析系统使用异步处理来同时处理多个包查找，从而提高大型依赖关系图的安装性能。

并发处理架构

PackageManager 维护一个任务队列和工作进程池，以并行处理依赖项，同时遵守注册表速率限制并优雅地处理故障。

来源: src/install/install.zig131-132 src/install/install.zig242-278

错误处理和回退

解析系统包括对网络故障、无效包规范和缺失依赖项的全面错误处理。

错误恢复机制

该系统针对瞬态网络错误实现了重试逻辑，并为解析故障提供有意义的错误消息，以帮助用户诊断依赖项问题。

来源: src/install/npm.zig191-237 src/install/install.zig271-277