bun-lockfile-update

Bun 锁文件更新

有关更新 Bun 锁文件（bun.lock）并采用恰当依赖管理实践的全面指南。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 bun-outdated……
运行 bun update 以刷新依赖项	审查过时的依赖项，但不进行任何更改
通过重新生成来解决 bun.lock 合并冲突	在决定是否升级前，审查主版本差异
修补特定软件包中的安全漏洞	列出单个软件包的较新版本
执行主版本升级工作流	引导全新检出时使用 bun-install

自动调用触发条件

在以下情况下自动使用此技能：

• 用户请求更新锁文件或刷新依赖项
• 用户提及过时依赖项或安全漏洞
• 用户想要更新特定软件包或所有依赖项
• Git 操作期间发生锁文件冲突
• 用户需要审计或验证依赖项完整性

核心命令

更新所有依赖项

# Update all dependencies to latest versions (respecting semver ranges in package.json)
bun update

# Update all dependencies AND modify package.json to latest versions
bun update --latest

更新特定依赖项

# Update specific package(s) to latest compatible version
bun update <package-name>
bun update <package1> <package2>

# Update specific package to latest version (ignoring semver range)
bun update --latest <package-name>

重新生成锁文件

# Regenerate lockfile from package.json (clean install)
rm bun.lock
bun install

# Or force regeneration
bun install --force

更新策略

1. 安全更新（推荐）

遵循 package.json 中的 semver 范围：

# Updates within semver constraints (^1.2.3 → 1.x.x, ~1.2.3 → 1.2.x)
bun update

# Review changes
git diff bun.lock package.json

# Test thoroughly
bun test
bun run build

适用场景：

• 定期维护更新
• CI/CD 流水线更新
• 生产部署
• 稳定性优先时

2. 激进更新

更新到绝对最新版本：

# Updates AND modifies package.json to latest versions
bun update --latest

# Review ALL changes carefully
git diff bun.lock package.json

# Test exhaustively (breaking changes likely)
bun test
bun run build
bun run lint

适用场景：

• 主版本升级
• 现代化改造工作
• 需要最新版本来修复安全漏洞
• 开发／实验分支

3. 选择性更新

仅更新特定软件包：

# Update one critical package
bun update lodash

# Update multiple related packages
bun update @types/node @types/react @types/react-dom

# Update to latest version (ignore semver)
bun update --latest typescript

适用场景：

• 针对性安全补丁
• 特定错误修复
• 渐进式迁移策略
• 降低变更的影响范围

最佳实践工作流

更新前检查清单

1. 提交当前状态： 确保工作目录干净

   git status
   git add .
   git commit -m "chore: checkpoint before dependency update"
   

2. 检查过时的软件包：

   bun outdated
   

3. 查看安全公告：

   bun audit
   

更新流程

1. 选择策略： 安全、激进或选择性更新
2. 执行更新命令
3. 审查变更：

   git diff bun.lock package.json
   

更新后验证

1. 验证安装：

   rm -rf node_modules
   bun install
   

2. 运行测试套件：

   bun test
   

3. 运行构建：

   bun run build
   

4. 运行代码检查：

   bun run lint
   

5. 检查包体积：

   bun run build --analyze  # If available
   

6. 手动测试应用：

   • 关键用户流程
   • 边缘情况
   • 跨浏览器测试（如果是 Web 应用）

提交变更

# For safe updates
git add bun.lock
git commit -m "chore(deps): update dependencies

Updates all dependencies to latest compatible versions.
All tests passing."

# For aggressive updates
git add bun.lock package.json
git commit -m "chore(deps): upgrade dependencies to latest

BREAKING CHANGES:
- Updated React 17 → 18
- Updated TypeScript 4.9 → 5.3
- Updated Vite 4 → 5

See CHANGELOG for migration notes.
All tests passing."

常见场景

场景 1：定期维护

目标： 保持依赖项更新，同时避免破坏性变更

# Weekly/monthly routine
bun update
bun test
git add bun.lock
git commit -m "chore(deps): update dependencies"

场景 2：安全漏洞

目标： 修补存在漏洞的特定软件包

# Check vulnerability report
bun audit

# Update vulnerable package to latest (may require --latest)
bun update --latest <vulnerable-package>

# Verify fix
bun audit

# Test and commit
bun test
git add bun.lock package.json
git commit -m "fix(deps): patch security vulnerability in <package>

Fixes: CVE-XXXX-XXXXX"

场景 3：主版本升级

目标： 迁移到框架／库的新主版本

# 1. Create feature branch
git checkout -b chore/upgrade-react-18

# 2. Update target package
bun update --latest react react-dom

# 3. Update related packages
bun update --latest @types/react @types/react-dom

# 4. Review breaking changes documentation
# (Check official migration guide)

# 5. Update code for breaking changes
# (Fix deprecated APIs, adjust imports, etc.)

# 6. Run comprehensive tests
bun test
bun run build
bun run lint

# 7. Manual testing
# (Test all critical flows)

# 8. Commit and create PR
git add .
git commit -m "chore(deps): upgrade React 17 → 18

BREAKING CHANGES:
- Automatic batching changes render behavior
- Updated ReactDOM.render to createRoot
- Removed IE 11 support

See docs/migration/react-18.md for details."

场景 4：锁文件冲突解决

目标： 解决 bun.lock 中的合并冲突

# 1. Accept either version (doesn't matter which)
git checkout --theirs bun.lock  # Or --ours

# 2. Regenerate lockfile from package.json
rm bun.lock
bun install

# 3. Verify installation
bun test

# 4. Commit resolution
git add bun.lock
git commit -m "chore: resolve lockfile merge conflict"

场景 5：依赖项审计与清理

目标： 移除未使用的依赖项并更新其余依赖项

# 1. Audit dependencies
bun pm ls  # List installed packages

# 2. Check for unused dependencies
npx depcheck  # Or manual review of package.json

# 3. Remove unused packages
bun remove <unused-package>

# 4. Update remaining dependencies
bun update

# 5. Verify everything still works
bun test
bun run build

Bun 专属功能

锁文件格式（bun.lock）

• 从 Bun 1.2 起，默认锁文件为基于文本的 bun.lock（JSONC）， 易于阅读，也便于在 git diff／PR 中审查。
• 旧版二进制文件 bun.lockb 仍受支持，但已不再是默认格式； 在 Bun ≥ 1.2 下运行 bun install 会将现有的 bun.lockb 迁移为 bun.lock （使用 bun install --save-text-lockfile 可强制迁移）。
• 由于 bun.lock 是文本文件，其合并冲突可以审查，且通常可以直接解决； 不过，重新生成（如下所示）仍是最简单的解决方法。
• 只提交一个锁文件：迁移后保留 bun.lock 并删除任何过时的 bun.lockb。

工作区

# Update all workspace packages
bun update

# Update specific workspace
bun update --filter <workspace-name>

兼容性

# Install with npm/yarn compatibility
bun install --backend=npm

# Generate package-lock.json for compatibility
bun install --lockfile-only

故障排除

锁文件损坏

# Symptoms: Install errors, checksum mismatches
# Solution: Regenerate lockfile
rm bun.lock
bun install

Peer 依赖冲突

# Symptoms: Peer dependency warnings during install
# Solution: Update peer dependencies or use --force
bun install --force

# Or resolve conflicts manually in package.json

缓存问题

# Clear Bun cache
rm -rf ~/.bun/install/cache

# Reinstall
rm -rf node_modules bun.lock
bun install

版本不匹配错误

# Symptoms: Package version doesn't match expectations
# Solution: Verify package.json and regenerate lockfile
cat package.json  # Check version ranges
rm bun.lock
bun install

安全最佳实践

定期审计

# Check for vulnerabilities
bun audit

# Get detailed report
bun audit --json > audit-report.json

自动更新

使用 Renovate 创建自动依赖项 PR——它会在修改 package.json 时原生重新生成并提交 bun.lock，因此更新／固定版本的 PR 会附带同步后的锁文件，无需额外配置。

• 不要对 bun 项目使用 Dependabot。 Dependabot 不会维护 bun.lock，因此它创建的 PR 会导致锁文件不同步。统一使用 Renovate（移除 .github/dependabot.yml）。
• postUpdateOptions 没有 bun 对应的值。 允许的值只有 npm/pnpm/yarn/bundler/go/nuget；虚构的值（例如 bunDedupe） 会导致 Renovate 的 allowedValues 验证失败，并破坏整个 配置。更新时无需任何选项即可获得匹配的锁文件。
• 启用 lockFileMaintenance，以定期全面刷新锁文件 （其 enabled 默认值为 false，因此需显式设置）。Bun 对此功能的支持曾出现回归，已由 Renovate PR #38694（2025 年 10 月）修复。

// renovate.json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "lockFileMaintenance": { "enabled": true }
}

审查依赖项

# Before updating, review package reputation
# Check npm package page, GitHub stars, maintenance status
bun pm ls <package-name>

锁文件完整性

# Verify lockfile matches package.json
bun install --frozen-lockfile  # CI/CD
bun install --production --frozen-lockfile  # Production

与 CI/CD 集成

GitHub Actions 示例

- name: Install dependencies
  run: bun install --frozen-lockfile

- name: Run tests
  run: bun test

- name: Update lockfile (scheduled job)
  run: |
    bun update
    bun test
  if: github.event_name == 'schedule'

Pre-commit Hook

# .husky/pre-commit or similar
#!/bin/sh
bun install --frozen-lockfile
bun test

相关技能

• Node.js 开发 - 使用 Bun 的现代 JavaScript/TypeScript 模式
• Git 分支 PR 工作流 - 管理依赖项更新 PR
• GitHub Actions 检查 - 调试 CI/CD 锁文件问题

参考资料

• Bun CLI 文档
• Bun 包管理器
• Bun 工作区
• 语义化版本