Lockfile 系统

相关源文件

• 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

Lockfile 系统管理依赖解析状态，并确保跨不同环境的可复现安装。它通过二进制和文本 lockfile 格式持久存储已解析的包版本、依赖项树和元数据。

有关使用 lockfile 的包安装过程的信息，请参阅 安装过程。有关依赖解析算法，请参阅 依赖解析。

Lockfile 格式

Bun 支持两种 lockfile 格式，并具备自动格式检测和迁移能力。

二进制 Lockfile (bun.lockb)

默认格式，使用高效的二进制序列化实现更快的解析速度和更小的文件大小。二进制格式使用 Lockfile.Serializer 进行加载和保存操作。

文本 Lockfile (bun.lock)

一种基于 JSON 的人类可读格式，用于版本控制和调试。文本 lockfile 使用 TextLockfile.parseIntoBinaryLockfile() 进行解析，并转换为内部二进制表示。

来源： src/install/lockfile.zig172-325 src/install/lockfile.zig328-356

核心数据结构

Lockfile 系统围绕 Lockfile 结构体，该结构体包含所有依赖项和包信息。

Lockfile 结构

来源： src/install/lockfile.zig1-27 src/install/install.zig214-217

字符串管理

Lockfile 使用复杂的字符串存储系统来最大化内存使用并支持高效的序列化。

• StringPool：管理字符串的去重和引用。
• string_bytes：原始字符串数据缓冲区。
• ExternalString：通过偏移量和长度引用字符串缓冲区。
• String.Builder：在 lockfile 构建过程中构建字符串。

来源： src/install/lockfile.zig14 src/install/install.zig135-137

加载过程

Lockfile 加载过程遵循基于优先级的机制，并带有回退策略。

来源： src/install/lockfile.zig182-325 src/install/migration.zig32-84

版本跟踪与完整性

Lockfile 系统实现了全面的完整性检查和版本管理。

Meta Hash 系统

meta_hash 字段包含一个 32 字节的哈希，代表 `package.json` 依赖项和配置的当前状态。这有助于检测需要 lockfile 更新的更改。

格式版本控制

format 字段使用 FormatVersion 来跟踪 lockfile 格式的演变并确保兼容性。

来源： src/install/lockfile.zig2-6 src/install/lockfile.zig775-799

迁移系统

Bun 提供从其他包管理器 lockfile 的自动迁移。

NPM Lockfile 迁移

迁移系统可以将 `package-lock.json`（版本 2 和 3）转换为 Bun 的格式。

来源： src/install/migration.zig32-84 src/install/migration.zig113-125

与包管理器的集成

Lockfile 系统与包管理器紧密集成，用于依赖解析和安装。

包管理器中的 Lockfile 操作

工作区支持

Lockfile 系统通过专门的数据结构支持 workspaces。

• workspace_paths：将 workspace 名称映射到文件系统路径。
• workspace_versions：将 workspace 名称映射到版本信息。
• Workspace 依赖项使用特殊的 Resolution.workspace 条目进行解析。

来源： src/install/lockfile.zig19-20 src/install/lockfile.zig654-713

保存格式选择

系统根据配置和现有 lockfile 自动选择合适的保存格式。

来源： src/install/lockfile.zig131-167 src/install/install.zig54-55