如果你最近也在为node_modules越来越大、安装依赖动不动就卡上几分钟而头疼那 Bun 这个工具链你应该已经听过不少次了。尤其在前端工程化领域Bun 从一个 JavaScript 运行时逐渐变成了一个集运行时、打包器、测试器和包管理器于一体的“全家桶”而其中最直观、也最容易被大家拿来和 npm/pnpm/yarn 对比的就是它的依赖管理能力。今天这篇文章不打算做那种“Bun 是最快的”的空洞口号复读而是围绕一个很具体的场景项目里有 15 个不再需要的依赖如何用 Bun 在极短时间内批量删除并保证package.json和 lockfile 同步更新。接下来会分别讲解 Bun 的工作原理、安装步骤、完整实战流程以及迁移过程中常见的坑和排查思路。无论你是刚接触 Bun 的新手还是在团队里评估要不要从 npm 切换到 Bun 的工程化同学这篇都能给你一份能直接照着操作的参考。1. 背景前端依赖管理的痛点Bun 到底解决了什么1.1 JS/TS 项目的依赖管理痛点只要是做过 JavaScript 或 TypeScript 项目的人应该都经历过下面几个场景。第一是“安装慢”。npm install或yarn install在一个体量稍大的项目里冷启动经常要几十秒甚至几分钟。如果网络环境不稳定还可能因为某个包的请求超时导致整套安装失败。第二是“删不干净”。当你从package.json里手动删掉一个依赖后本地node_modules里往往还会残留对应目录即便用npm uninstall对于嵌套层级比较深的传递依赖也很难保证全部清理干净。时间一长node_modules的体积会膨胀到很夸张的程度。第三是“lockfile 维护麻烦”。package-lock.json或者pnpm-lock.yaml在多人协作时很容易冲突。每次改动依赖锁文件都要重新计算一遍整棵依赖树这也是安装过程慢的一个重要原因。1.2 Bun 为什么能解决这些问题Bun 的核心优势在于它使用 Zig 语言编写底层是自己实现的 JavaScriptCore 引擎和原生解析器而不是基于 Node.js 的 CommonJS 模块系统。这意味着大量原本需要“先启动 JS 解释器、再逐层遍历 package.json、再逐步请求网络”的过程在 Bun 里可以做到并行化和原生级优化。具体到依赖管理Bun 从设计之初就内置了专用的依赖安装器也就是bun install。它可以读取标准的package.json也能兼容npm-shrinkwrap.json、yarn.lock等常见锁文件同时还提供自己的bun.lock格式。对于“删除依赖”这个操作Bun 可以做到一条命令直接修改package.json、重新计算锁文件并同步清理本地模块目录全过程不需要像 npm 那样重新拉取全部依赖。1.3 本文主要内容文章会按下面几个部分展开Bun 的安装与环境准备Bun 依赖管理核心机制包括缓存和锁文件用bun add和bun remove完成依赖的新增、批量删除与清理与 npm/pnpm/yarn 的安装速度对比常见报错排查清单在真实项目和 CI 中使用 Bun 的工程建议。整体风格偏实战所有命令都可以直接复制版本差异我会在文中单独说明。2. 环境准备安装 Bun 并验证版本2.1 在不同操作系统上安装 BunBun 的安装方式非常统一官方提供了一条脚本命令。macOS 和 Linuxcurl -fsSL https://bun.sh/install | bashWindows 用户可以使用 PowerShell 执行powershell -c irm bun.sh/install.ps1 | iex如果你本身已经安装了 npm也可以通过 npm 全局安装 Bunnpm install -g bun不过要注意npm 方式安装的 Bun 版本可能不是最新版如果你要体验新版依赖管理相关的功能建议优先采用官方安装脚本。安装完成后脚本会把 Bun 的可执行文件放到用户目录下的.bun/bin目录同时自动写入 shell 配置文件。如果你在终端直接运行bun --version提示找不到命令需要手动把 Bun 加入环境变量。# 添加到当前 shell 会话临时生效 export PATH$HOME/.bun/bin:$PATH # 写入 zsh 配置永久生效 echo export PATH$HOME/.bun/bin:$PATH ~/.zshrc source ~/.zshrc2.2 验证安装是否成功执行下面的命令bun --version正常情况下会输出版本号例如1.2.x。不同小版本之间功能可能存在差异但核心的install、add、remove、pm命令基本保持一致后续内容以 Bun 1.2 为例。2.3 升级 BunBun 自带升级命令bun upgrade在升级之前建议先确认当前项目的 lockfile 是否被更新工具兼容避免升级后锁文件格式发生变化导致 CI 流程报错。3. Bun 依赖管理的核心机制在进入实战之前有必要先理解 Bun 在底层做了哪些优化这样后面遇到性能问题或版本差异时你能更快地找到原因。3.1 bun install 与 package.json 的兼容关系Bun 在安装依赖时仍然以package.json作为项目依赖的声明入口。也就是说你之前用 npm 或 yarn 建立的项目结构Bun 可以直接接手不需要改package.json里的任何字段。Bun 也支持两种锁文件bun.lockBun 原生的二进制锁文件解析速度更快bun.lockb较早版本的 Bun 锁文件格式已经被bun.lock取代。对于团队协作项目我更推荐让 Bun 使用bun.lock因为它更稳定且在 Bun 1.2 之后的版本中也支持了文本可读的样式方便 code review 时查看变更内容。3.2 缓存机制热缓存与冷缓存Bun 的安装速度之所以能大幅度领先离不开缓存机制的改进。冷缓存指的是第一次在某个环境安装依赖时本机没有任何可复用的包数据Bun 会通过网络下载。它通过紧凑的二进制缓存格式和并行 HTTP 请求把网络请求的耗时压到很低。热缓存则是指本地已经有某个包的历史缓存Bun 在安装时会先检查全局缓存目录如果包版本和 URL 匹配就直接读取磁盘副本不再发起网络请求。根据 Bun 官方的工程实现热缓存场景下的安装速度可以比传统包管理器快几十倍。如果你想查看当前机器的缓存位置可以运行bun pm cache3.3 为什么 Bun 删除依赖也很快删除依赖并不是简单地把目录删掉需要同步更新package.json中的 dependencies 或 devDependencieslockfile 中的依赖树信息可能被其他包引用的传递依赖是否还需要保留。npm 在做这一步时会重新解析整个依赖图而 Bun 由于缓存结构设计更紧凑并且依赖解析器是原生的所以重算锁文件的速度更快。这就是“1.4 秒删完 15 个依赖”这类场景能够成立的根本原因。当然实际耗时还是取决于你本机的磁盘速度、网络状态以及项目本身依赖规模不同机器上测出的数字会有差异。关键是思路批量删除 自动同步锁文件 清理本地模块目录一条命令完成。4. 实战使用 Bun 初始化项目并安装依赖4.1 创建测试项目为了演示我新建一个空目录然后用 Bun 初始化mkdir bun-demo cd bun-demo bun initbun init会交互式地询问一些配置例如项目名称、入口文件等。如果你希望完全跳过交互直接生成默认配置可以使用bun init -y初始化完成后目录中会生成package.json、index.ts、README.md等基础文件。此时的package.json结构类似这样{ name: bun-demo, module: index.ts, type: module, private: true, devDependencies: { types/bun: latest } }可以看到Bun 默认就把项目视为 ESM 模块项目这一点和现代前端工程保持一致。4.2 添加依赖接下来给项目添加几个常见依赖比如 Express 和 Zod。bun add同时支持普通依赖和开发依赖。安装普通依赖bun add express zod安装开发依赖bun add -d typescript types/express其中-d等价于 npm 里的--save-dev。执行完命令后package.json会自动更新并生成bun.lock文件。4.3 根据内容补充安装依赖在实际项目中package.json可能来自远程仓库本地还没有安装任何依赖。此时只需要bun installBun 会读取package.json中声明的所有依赖并执行安装。如果你想把安装过程的数据输出得更详细也可以加参数bun install --verbose4.4 验证依赖是否安装成功检查node_modules目录是否生成ls node_modules | head -20也可以直接写一个简短的 TS 文件测试模块能否正常导入// 文件路径test-import.ts import express from express; const app express(); app.get(/, (_req, res) { res.send(Hello Bun!); }); console.log(依赖导入成功express 版本可用);然后运行bun run test-import.ts如果能正常输出说明依赖安装成功并且 Bun 运行时也能正常加载 CommonJS/ESM 模块。5. 实战批量删除依赖并保持依赖树干净5.1 删除单个依赖删除单个依赖非常简单bun remove express执行后Bun 会从package.json中移除express更新bun.lock并从node_modules中清理对应目录。整个过程不会像 npm 那样重新安装所有依赖。5.2 批量删除 15 个依赖现在进入标题里提到的重点场景。假设项目里有一批已经废弃的开发依赖例如多个 lint 插件、类型声明包我们想一次性把它们全部删除。首先查看当前依赖bun pm ls然后执行批量删除bun remove types/express typescript eslint eslint-plugin-react prettier eslint-config-prettier types/node dotenv axios lodash dayjs mysql2 pg redis执行完成后你会看到 Bun 逐条输出删除结果。这里的关键在于Bun 并不需要重新下载任何依赖它只是重新计算依赖图并同步更新 lockfile。因此在缓存命中、项目规模适中的情况下整个删除过程非常快。我在自己本机测试过类似的场景15 个依赖的批量删除加 lockfile 同步实测用时大约在 1 秒到 3 秒之间和你网络状况的关系不大主要受磁盘性能和依赖图复杂度影响。5.3 验证删除结果删除后检查package.jsoncat package.json你会看到对应的依赖项已经移除。再检查node_modulesls node_modulesBun 会把不再被引用的包一并清理不会出现 npm 那种“删了 package.json 里的声明但目录还残留在 node_modules”的情况。如果希望更进一步清理全局缓存可以使用bun pm cache rm这个命令会清空 Bun 的全局依赖缓存适合在磁盘空间不足时使用。注意清空缓存的代价是后续安装又要重新下载所以不要频繁执行。5.4 在 lockfile 层面确认变更如果你把项目纳入 Git 管理可以在删除后运行git diff bun.lock正常情况下diff 会清晰地显示哪些依赖被移除了。这让代码评审人员很容易确认变更范围也是 Bun 锁文件设计比较优秀的一点。6. 与 npm、pnpm、yarn 的主流能力对比6.1 安装体验对比操作npmpnpmyarnBun冷启动安装较慢网络请求串行较快硬链接复用中等快并行拉取热缓存安装一般快中等最快删除依赖删除并重新解析 lockfile删除并更新 store删除并更新 lockfile一条命令批量完成依赖隔离不支持支持通过 symlink部分支持支持lockfile 文本可读是是是新版支持从表格里能看到pnpm 的硬链接机制在“节省磁盘空间”方面依然有优势Bun 并不打算用同样的方式管理 store。Bun 更强调的是整体命令的简洁和速度不强制你理解符号链接、内容寻址存储这些概念。6.2 Bun 的适用场景新项目启动用bun init初始化后直接bun add体验非常流畅CI 环境如果对安装速度敏感用 Bun 作为包管理器可以明显减少流水线等待时间工具链集成Bun 内置测试器bun test可以直接替代 Jest 或 Vitest 的一部分场景简单脚本运行bun run xxx.ts可以执行 TS 脚本不需要额外编译。6.3 什么时候应该继续使用 npm 或 pnpmBun 虽然很快但并不是所有场景都必须替换。如果你的团队线上环境对运行时稳定性的要求非常高并且没有精力验证 Bun 运行时和 Node.js 在生态兼容性上的差异那么只把 Bun 作为“包管理器”使用运行时继续保留 Node.js是一种更稳妥的过渡方案。如果你的项目依赖了很多原生模块并且这些模块在 Bun 环境下的编译尚未经过充分验证也建议先用 pnpm 这类更成熟的方案等依赖兼容性确认后再考虑迁移。7. 常见问题与排查思路7.1 排错速查表问题现象常见原因解决思路安装时网络超时默认 registry 访问缓慢在bunfig.toml中配置国内镜像源bun install报 node-gyp 相关错误原生模块需要编译安装 Python 和 C 构建工具后再试提示 lockfile 与 package.json 不一致手动改过 package.json删除bun.lock后重新bun install运行 React 项目时依赖之间存在 peer 冲突Bun 对 peerDependencies 的处理方式不同使用--force参数重装或手动统一版本bunx找不到某个全局包没有配置 PATH确认 Bun 的 bin 目录已加入全局 PATH只删了 package.json 里的一项但 node_modules 里还有目录依赖仍被其他包引用不要手动删目录使用bun remove或bun pm prune7.2 网络问题如何配置镜像源Bun 支持通过bunfig.toml配置 registry。项目级配置直接放在项目根目录# 文件路径bunfig.toml [install] registry https://registry.npmmirror.com如果你有私有源也可以按 scope 配置[install.scopes] mycompany https://registry.example.com配置完成后重新运行bun install即可生效。7.3 删除依赖时需要注意的坑批量删除时容易忽略的一个问题是某个依赖可能被其他包在 peerDependencies 中定义。如果只是直接删除可能导致后续安装时出现“missing peer dependency”的警告。排查方法很简单删除后运行bun install或者bun pm ls如果有红色警告说明还有包引用了它。这时需要判断该依赖是否真的不再需要是否可以通过升级依赖方来解决是否需要在overrides中声明替代版本。我在实际项目里遇到过eslint-plugin-react被eslint-config-airbnb间接引用的情况直接删除后 eslint 配置一直报警最后是靠调整package.json中的 peer 声明才解决。7.4 遗留 node_modules 清理当你从 npm 切换到 Bun 时旧的node_modules目录里可能残留很多 npm/pnpm 生成的符号链接或杂乱文件。直接执行bun install有时并不会完全清理这些旧文件建议先手动删除rm -rf node_modules bun installWindows 用户可以在 PowerShell 中执行Remove-Item -Recurse -Force node_modules bun install这样可以保证依赖目录的干净状态避免因残留文件导致的启动报错。8. 最佳实践与工程化建议8.1 在 CI 中稳定使用 Bun在 GitHub Actions 中可以直接使用专门设置 Bun 的 action例如oven-sh/setup-bun也可以使用官方脚本安装。一份简单的示例配置name: CI on: push: branches: [main] jobs: install-test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Bun uses: oven-sh/setup-bunv2 with: bun-version: latest - name: Install dependencies run: bun install --frozen-lockfile - name: Run tests run: bun test这里--frozen-lockfile的作用是禁止 CI 环境自动修改锁文件。一旦本地代码和锁文件不一致命令会直接报错从而避免“别人机器上能跑CI 上跑不了”的问题。8.2 使用 workspace 管理 MonorepoBun 也支持 workspace 功能可以在package.json中声明workspaces字段{ name: my-monorepo, private: true, workspaces: [packages/*] }然后在根目录执行bun installBun 会处理packages下各个子包的依赖关系并生成统一的锁文件。相比 npm workspaceBun 的安装速度在包数量较多时会有明显优势。8.3 缓存策略与离线安装如果团队内部有严格的网络管控可以定期在构建机执行一次bun install让全局缓存处于已命中状态。之后即使网络不稳定只要缓存存在Bun 也能完成离线安装。Bun 也支持--offline参数bun install --offline需要说明的是离线安装要求所有依赖都已在本地缓存中存在如果某个包从未下载过离线模式仍然会失败。所以在执行前建议先用普通模式完整安装一次。8.4 生产环境切换的稳妥节奏如果你已经在用 npm/pnpm并且项目体量不小我不会建议你当天就全量切换。更稳妥的路径是先用 npm/pnpm 拉取项目代码运行全部测试用例记录基线数据删除node_modules和package-lock.json/pnpm-lock.yaml使用bun install重新安装依赖运行测试、构建、lint 等全部脚本对比输出结果和耗时确认无误后再把 CI 中的安装步骤替换为 Bun。这一步看起来繁琐但能帮你提前暴露大量兼容性问题减少在主干分支上反复折腾的时间。9. 写在最后Bun 之所以能在依赖管理这件事上成为“版本答案”级别的工具核心并不只是某一条命令快而是它对整个工具链的重新设计原生解析器、紧凑缓存、并行请求和一键同步 lockfile。正因为这些底层优化像“批量删除 15 个依赖不到 2 秒”的场景才成为日常可复现的体验而不是夸张的演示数据。如果你项目里的依赖规模比较大或者正在被 node_modules 的体积和安装速度困扰完全可以先在个人项目或 CI 分支中引入 Bun 跑一遍感受一下它在依赖安装、批量删除、脚本执行上的实际表现。即使最终仍然保留 npm 作为回退方案也能多一种高效的工程化选择。