企业官网建设流程全解析

Bun 1.4 相关讨论里，最抓眼球的一幕，是一次性删掉 15 个项目依赖。命令敲下去，终端几乎不需要停顿，package.json、bun.lockb、node_modules 就完成了同步。对常年被 npm install 和 Maven 依赖问题卡住的人来说，这种体验很反常识。其实 Bun 能“秒删依赖”，核心不是删除动作本身，而是它把依赖管理里的很多步骤提前做完了。这篇文章会沿着 Bun 依赖管理的命令、机制、验证、排查和最佳实践展开，既讲怎么用，也讲为什么快，还会补充在生产环境里容易踩的坑。

1. 先厘清一个前提：Bun 的依赖管理到底管什么

1.1 包管理器要解决的三个核心问题

无论是 npm、pnpm、Yarn 还是 Bun，依赖管理都必须解决三个问题：解析、锁存、落地。解析是根据 package.json 里的声明去 registry 拿元数据，算出当前应该安装哪个版本；锁存是把解析结果固定下来，防止不同时间安装出不同版本；落地是把依赖包实际放到 node_modules 或者系统缓存里，让代码能 import 到。

传统工具的问题，恰恰是这三步都必须依赖整个依赖图。比如 npm 在执行 install 时，经常需要对几十个包做网络请求，每请求一个包，又要去读它的 dependencies，再继续请求下一层。项目只要稍微复杂，时间就会成倍增加。Maven 和 Gradle 类似，也需要从远程仓库拉 POM 和 jar 包；如果网络源不稳定，就会出现依赖缺失、无法安装的问题。Vue、Flutter、Docker 安装场景里的依赖报错，根源也大多是版本约束、网络、缓存和生命周期脚本之间的冲突。

很多基于 .deb 的 Linux 环境，安装 mysql 或 onlyoffice 时会出现“依赖关系不满足 fonts-dejavu”或“无法安装 libaio1”这类错误；在 Python 项目里，服务端忽略了 requirements.txt，代码一启动就 ModuleNotFoundError；在 Flutter 工程里，不同插件版本约束互相冲突，依赖一直拉不下来。这些表面问题不同，底层都落在“解析-锁存-落地”三个环节里。Bun 做依赖管理时，并没有发明新的依赖理论，而是把这三个环节用原生代码高度并行地实现，同时把中间步骤简化到最少。

1.2 Bun 将“安装、运行、打包”整合成一条链路

Bun 不只是包管理器，它还是 JavaScript 和 TypeScript 运行时、测试运行器和打包器。这种一体化直接影响依赖机制的设计：Bun 不需要通过 Node.js 进程来驱动 npm 脚本，它的包管理逻辑和运行时共享同一套模块解析策略。安装依赖时，它可以直接处理 JS、TS、JSON 甚至 wasm 的导入路径；运行时遇到 import 时，能直接命中 Bun 自己的安装布局。

这也是为什么 Bun 的问题看起来更少：它安装出来的 node_modules 布局，是和它的运行时互相匹配的。反观 npm，既要考虑 Node 老版本的模块解析，又要兼容各种工具链把入口要求追加进去，很多无关工作都会被塞进安装流程。

1.3 不要神化“秒删”，要把它当成设计目标的结果

“秒删 15 个依赖”这个现象，不是某个命令单独调优出来的，而是 Bun 把包管理整体设计成“少做事”的结果。它安装时不做多余解析、删除时不需要重建整棵依赖树，所以命令看起来像“删文件”而不是“重新安装”。这一点会直接影响后面理解 bun.lockb 和缓存的作用。

2. 准备实验环境：先能在本地跑起 Bun 1.4 的依赖命令

2.1 安装 Bun 并确认版本

在 macOS 或 Linux 上，推荐使用官方安装脚本：

curl -fsSL https://bun.sh/install | bash

在 Windows 上，可以通过 PowerShell 或 npm 安装：

powershell -c "irm bun.sh/install.ps1 | iex"

npm install -g bun

安装完成后，先确认当前使用的版本：

bun --version

如果你在项目里同时安装了 npm 和 bun，建议先明确当前 CLI 是哪个，避免命令回调到不同路径。文章里出现的命令以 Bun 主流版本行为为基础，具体小版本如果与官方 release notes 不一致，要以官方文档为准。

2.2 初始化一个带 15 个依赖的实验项目

为了还原“一次删掉 15 个依赖”的场景，可以先创建一个空项目：

mkdir bun-remove-demo && cd bun-remove-demo bun init -y

bun init 会生成 package.json、入口文件等基础结构。接下来添加 15 个纯 JS 依赖，用这些依赖模拟一个依赖关系比较杂的项目：

bun add lodash axios dayjs chalk commander express fast-glob glob minimist nanoid react react-dom uuid zod yaml

命令执行完后，package.json 的 dependencies 会出现 15 项。这里选择的包彼此没有强依赖关系，更适合做“纯删除操作”的时间对比，不会因为某个子包绑定其它依赖而导致结果失真。

2.3 安装并生成锁文件

再执行一次标准的安装命令：

bun install

命令完成后，项目目录下会出现 bun.lockb。这个文件是二进制的，不建议直接编辑，也不适合交给普通文本合并工具处理。如果项目之前用的是 package-lock.json，切换到 bun install 之后，旧的 lockfile 不会被自动纳入 bun 的锁文件体系；从切换这一刻开始，建议只维护 bun.lockb。

2.4 用 time 感受一次真实删除

现在可以复现“秒删 15 个依赖”的操作：

time bun remove axios chalk commander dayjs express fast-glob glob lodash minimist nanoid react react-dom uuid zod yaml

观察三个地方：

• package.json 里 dependencies 中对应的 15 项已经消失。
• bun.lockb 被重新生成或更新。
• node_modules 里对应的包目录不再存在。

同样的删除操作，如果用 npm 来执行，往往需要对剩余依赖重新做一次解析和磁盘扫描，项目越复杂，差异越明显。这里的“秒删”并不代表 0 毫秒，而是说 Bun 在删除时不需要重建整棵依赖树。

3. 核心命令与参数拆解：从 install 到 pm

3.1 bun install 的常用参数

bun install 负责把 package.json 里声明的依赖安装到本地。它常用参数如下：

在 CI 流水线里，推荐这样使用：

bun install --frozen-lockfile --production

3.2 bun add：加依赖时控制版本范围

bun add 负责新增依赖。它支持常见的包名写法：

bun add zod bun add zod@3 bun add -d typescript

第一条命令添加最新版本；第二条锁定在 3.x 大版本内；第三条把依赖写到 devDependencies。命令执行后，package.json 和 bun.lockb 会同步更新。这里要特别注意，bun add 不是简单往 package.json 塞一个字段，它会真正解析这个包及其传递依赖，并把结果写进锁文件。

3.3 bun remove：一次删除多个依赖

这是“秒删 15 个依赖”的直接操作命令。基本用法：

bun remove <pkg>...

它支持一次传入多个包名。执行删除时大约会做三件事：

1. 从 package.json 中删除对应的直接依赖声明。
2. 更新 bun.lockb，去掉与该包相关的锁存条目。
3. 清理 node_modules 中对应该包的目录和索引。

与直觉不同，bun remove 不会立刻扫描磁盘上的所有嵌套 node_modules 来“清扫垃圾”。它只处理直接关联的部分，其它空间留到后续的缓存回收或 install 操作再处理。这也是它速度感更强的原因之一。

有两点容易误解：

• 如果 react 仍然被项目里的其它包间接依赖，bun remove react 只会移除 package.json 里的直接声明，不能保证把 react 从所有引用中彻底清走。
• 如果包名拼写错误，Bun 会提示未找到对应的直接依赖，不会静默成功。

3.4 bun update：控制版本漂移

bun update 用来按 package.json 里的 semver 范围更新依赖：

bun update bun update zod bun update --latest

第一种会更新所有依赖到当前声明范围内允许的最新版本；第二种只更新指定包；第三种会忽略 semver 范围，直接升到 registry 上的最新版本。第三种操作风险最高，因为 major 版本升级往往包含破坏性变更，运行时会很快暴露问题，但排查成本也不低。

推荐策略是小步更新：一次只更新一个或几个包，然后跑测试确认，再继续下一批。

3.5 bun pm：查看缓存和依赖树

pm 子命令提供了和依赖管理相关的辅助能力：

bun pm ls bun pm cache bun pm bin

bun pm ls 会输出当前项目的依赖列表或依赖树。当怀疑某个包没有安装成功时，先看它是否在列表里。bun pm cache 能显示全局缓存的路径，配合缓存清理能解决不少“改了代码却没生效”的假象。bun pm bin 会打印可执行文件所在目录，适合排查命令行工具找不到的问题。

如果依赖丢失，可以用这些命令确认到底缺的是哪个层级，再决定是重装单个包，还是清理缓存后完全重装。

4. 为什么快：从实现机制看“删除 15 个依赖”

4.1 原生执行引擎减少进程启动开销

Bun 使用 Zig 和 C++ 编写核心逻辑，包管理逻辑内嵌在运行进程里。执行 bun remove 时，不需要像 npm 那样再拉起一个 Node.js 进程、初始化完整事件循环、加载一堆 npm 自身模块，因此仅进程启动开销就低很多。

对一次性命令来说，这条优势非常明显。npm 的项目越用越慢，一部分原因就是每次命令都要经历完整启动流程和依赖加载；Bun 把常用操作编译成紧凑的原生代码，启动路径短，指令数量也更少。

4.2 node_modules 扁平布局与全局缓存

Bun 在安装依赖时依赖全局缓存。如果某个包已经在缓存里，bun install 不需要再次下载。它在项目 node_modules 中落地的速度，主要取决于文件系统操作，而不是网络。

Bun 的 node_modules 布局整体上是扁平的，顶层目录和 package.json 的直接依赖一一对应。删除包时，只需要确认它在顶层目录中的索引可以被移除，再更新锁文件里的相关条目，不需要对整棵依赖树重新做一次递归解析。这也是“秒删”的直观原因。

注意，这里不能把 Bun 的缓存机制和“所有安装都瞬间完成”画等号。冷缓存时，第一个项目的安装仍然要下载大量包，快的是缓存命中后的增量操作。

4.3 二进制锁文件是整个依赖图的结果缓存

bun.lockb 采用二进制格式，把解析结果按 Bun 内部数据结构直接序列化。相比 JSON 文本格式，读取和反序列化的成本更低。执行 bun remove 时，Bun 在确认要删除的包之后，只需要修改锁文件里相关条目的引用，再对 node_modules 做增量清理，不需要回到 registry 重新查询版本。

这个设计目标是让锁文件成为“依赖图的结果缓存”，而不是一份可以手工阅读的账本。带来的代价是二进制文件不便于自动 diff 和 merge，团队协作时需要统一工具链。

4.4 并行化下载、解析与校验

Bun 使用多线程并发处理网络请求和文件操作。在大项目里，它可以在一个安装任务里同时请求多个包，而不是像一些传统工具那样串行遍历依赖队列。删除依赖时，并行校验多个包的依赖关系也能节省时间。

这个速度优势在冷缓存、新机器上最明显。热缓存时更多体现为文件系统操作和锁文件更新时间，差距会缩小，但整体仍然比传统工具轻快。

5. 生产环境落地的真实问题：为什么“快”反而要小心

5.1 二进制锁文件不能像 JSON 那样通用，混用工具会冲突

bun.lockb 是二进制格式，直接 diff 或 merge 都不方便。如果团队里一部分人用 npm，一部分人用 Bun，两个包管理器会各自生成不同锁文件，互相覆盖后出现不可复现的安装结果。

建议团队统一包管理器。如果遇到 npm 工程师在分支里更新了 package.json，Bun 用户需要重新执行 bun install 生成新 bun.lockb，并把这个变更明确写进提交说明。不要把 package-lock.json 和 bun.lockb 同时维护成两套事实。

5.2 lifecycle scripts 策略影响原生模块

某些 npm 包依赖 postinstall 脚本去下载二进制、编译原生模块，比如 sharp、esbuild、node-sass 等。Bun 出于安全考虑，不会默认允许所有包执行 lifecycle scripts。如果该包没有写进 trustedDependencies 白名单，install 可能看上去成功，实际运行时却找不到对应二进制文件。

安装这类依赖时，可以使用 Bun 对包或包名的信任配置：

bun add sharp

如果发现缺少二进制，可以尝试重新安装并把该包加入受信任列表：

bun add sharp --trusted

在生产构建里，不要把“所有包都信任”当成默认值。白名单应该只放行确实需要脚本的包，这样能减少供应链脚本被滥用时的风险面。

5.3 全局缓存不是一劳永逸，坏缓存会造成假阳性

如果某个依赖在全局缓存里损坏，bun install 可能直接使用坏文件，导致运行时出现莫名的模块缺失或版本错位。排查时可以清掉缓存再重装：

bun pm cache rm

但不要一上来就清缓存。先看报错信息，确认是不是某个包的完整性有问题，再决定是否清理。生产环境里频繁清理全局缓存会拖慢每一次安装，不是推荐做法。

5.4 workspace 与 monorepo 场景

Bun 支持 workspace。在根 package.json 声明：

{ "workspaces": ["packages/*"] }

运行 bun install 会同时解析所有子包。此时在根目录执行 bun remove 删除共享依赖没有特殊问题，但如果要删除某个子包里的依赖，应该在对应子包目录里执行，并确认其它 workspace 没有引用它。稍不留神会在 CI 中出现“本地能跑，流水线里找不到依赖”的现象。

5.5 生产镜像里的构建注意点

使用 Docker 部署时，建议使用 Bun 官方镜像，并在构建阶段明确安装模式：

FROM oven/bun:1 AS builder WORKDIR /app COPY package.json bun.lockb ./ RUN bun install --frozen-lockfile --production COPY . . CMD ["bun", "run", "start"]

生产阶段不应该依赖开发机缓存。构建镜像时，尽量使用 frozen-lockfile 保证可复现；镜像构建完成后，可以通过清理缓存或利用镜像层回收来控制体积。不要为了“看起来更快”而在生产镜像里重复安装全套 devDependencies。

6. 依赖管理的通用最佳实践，不只是 Bun 的事

6.1 锁文件必须进版本库

无论使用什么包管理器，锁文件都是可复现安装的底线。对于 Bun，bun.lockb 应该提交到 git，并纳入分支保护。如果锁文件总在变化，说明当前流程里存在不稳定因素，比如混用包管理器、Bun 版本不一致，或者某些依赖使用了不固定的版本范围。

在每次提交前，可以问自己一句：如果 CI 在完全干净的环境里执行相同命令，能拿到和我本地一样的依赖图吗？锁文件是回答这个问题的关键。

6.2 把“学习环境”和“生产构建”分开

学习时为了省时间，可以依赖全局缓存、临时目录，直接改 package.json 再 install。生产构建必须满足以下条件：

• 固定近期验证过的 Bun 版本。
• 使用 frozen-lockfile 阻止隐性变更。
• 不依赖开发机缓存。
• 在干净环境验证一次冷安装。
• 检查锁文件变更的触发原因。

这样能避免“我本地没问题，但服务器装不出同一套依赖”的经典事故。

6.3 升级策略：小步走，单包验证

推荐“大版本锁定，小版本更新”。示例：

bun update zod bun add axios@^1.2.3

不要盲目执行 bun update --latest，更不要在 CI 里自动升级全部依赖。依赖升级不是包管理器一个命令能解决的问题，它涉及到 API 兼容性、运行行为变化和安全影响，应该交给人工测试来把控。

6.4 安全维度：依赖审计与白名单

Bun 生态的安全工具仍在快速演进。对安全要求高的项目，建议在 CI 中叠加 npm audit 或 OSV-Scanner 等工具扫描锁文件，对引入的依赖做许可和来源评估。维护 trustedDependencies 白名单时，只放行确实需要 scripts 的包，并记录放行理由。

依赖安全不是一次检查就能结束的事。新依赖加入时要做一次评估，已依赖包出现新漏洞时也要能快速定位到使用位置。

6.5 可复用检查清单

依赖相关的检查，可以按这个顺序过一遍：

• bun --version 与团队定义版本是否一致。
• 项目里是否存在多个包管理器在同时维护 lockfile。
• bun install --frozen-lockfile 能否在干净目录通过。
• package.json 中是否有长期未被引用的历史依赖。
• CI 是否依赖本地缓存或开发机环境。
• trustedDependencies 白名单是否最小化。
• 需要编译原生模块的依赖，能否在生产基础镜像里完成构建。
• 安全扫描报告是否存在高危漏洞，是否有关联任务跟进。

7. 常见问题排查：从现象到解决方案

7.1 错误现象与处理表

7.2 排错链路

依赖问题的排查顺序，应该从“输入是否正确”开始，逐步向“环境是否可用”推进：

1. 先确认执行的命令和上下文，包名是否拼写错误，是否在正确的 package.json 目录里执行。
2. 再看日志，Bun 的报错通常会指明模块或文件位置。
3. 验证锁文件是否干净，运行 bun install --frozen-lockfile，如果失败说明锁文件与 package.json 不一致。
4. 尝试用 bun pm cache 查看缓存状态，确认缓存路径是否异常。
5. 检查权限、磁盘空间、网络源和 registry 配置。
6. 仍然无解时，删除 node_modules 和 bun.lockb 重新安装。这个操作只适合本地确认安全后再执行。

其中，最容易忽略的是第 3 步。很多人遇到依赖问题后先清缓存或重装，结果发现根因是 lockfile 已经和 package.json 失配，重装只会把问题掩盖一段时间。

7.3 从 npm 项目迁移到 Bun 的注意

迁移的第一步不是删掉旧锁文件，而是先备份。推荐顺序：

1. 提交当前项目的 package-lock.json 与 node_modules 状态。
2. 备份现有 node_modules，再执行 bun install。
3. 对比本地运行结果，确认行为差异。
4. 如果项目使用 C++ 插件、Electron 或者某些依赖绝对路径查找，Bun 的模块解析可能和 Node 不同。
5. 不要一次迁移全部项目，先挑一个非核心服务验证真实场景。

迁移后最常出现的疑问是“为什么本地能跑，CI 跑不了”。这时要同时检查 Bun 版本、node_modules 缓存、lockfile 差异、系统依赖和权限设置。

Bun 1.4 能不能在每台机器上都做到秒删 15 个依赖，取决于缓存、网络、项目复杂度和文件系统。但它给依赖管理带来的真正价值，是把安装、运行、构建之间的偏差压缩到最小。拿到命令之后，建议先做一次最小的 15 依赖实验，把 bun remove、bun add、bun install 和 bun.lockb 的行为摸清楚，再分批迁移到真实项目里。版本、脚本、锁文件和团队规范这四件事，比任何性能数据都更值得长期维护。