bun-validator

Bun 验证器

何时启用

• 设置新的 Bun 单仓库
• 向工作区添加依赖项之前
• 审核现有 Bun 工作区
• AI 生成 package.json 文件之后
• CI/CD 流水线验证

快速开始

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --strict

检查内容

1. Bun 版本

# GOOD: v1.3+
bun --version  # 1.3.0 or higher

# BAD: v1.2 or earlier
bun --version  # 1.2.x

2. 根 package.json

正确 - 单仓库根目录：

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

错误 - 根目录中包含依赖项：

{
  "workspaces": ["apps/*"],
  "dependencies": {
    "react": "^19.0.0"  // BAD: Don't put deps in root
  }
}

3. 工作区结构

正确： 完整目录树请参见 references/full-guide.md（§ 工作区结构示例）——根目录包含 package.json 和 bun.lockb，每个应用/包都有自己的 package.json。

错误：

my-monorepo/
├── package.json
├── apps/
│   └── web/
│       ├── package.json
│       └── bun.lockb     # BAD: Lockfile in workspace

4. 工作区依赖项

正确 - 使用工作区协议：

{
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/config": "workspace:^1.0.0"
  }
}

错误 - 使用硬编码版本：

{
  "dependencies": {
    "@myorg/ui": "1.0.0"  // BAD: Use workspace:*
  }
}

5. 依赖项目录（Bun 1.3+）

正确 - 集中管理版本：

// Root package.json
{
  "catalog": {
    "react": "^19.0.0",
    "typescript": "^5.7.0",
    "@types/node": "^22.0.0"
  }
}

// apps/web/package.json
{
  "dependencies": {
    "react": "catalog:"  // Uses version from catalog
  }
}

6. 隔离安装

正确 - Bun 1.3 中的默认设置： 包只能访问其显式声明的依赖项。

错误 - 提升依赖项：

// Don't disable isolation
{
  "workspaces": {
    "packages": ["apps/*"],
    "nohoist": ["**"]  // Don't do this
  }
}

Bun 1.3+ 功能

依赖项目录

目录语法请参见上文 § 依赖项目录（Bun 1.3+）。

交互式更新

bun update --interactive  # Selectively update deps

依赖链

bun why react  # Explain why a package is installed

工作区命令

# Install in specific workspace
bun add express --cwd apps/api

# Run script in workspace
bun run --cwd apps/web dev

# Run in all workspaces
bun run --filter '*' build

常见问题

问题：“Cannot find module”

原因： 工作区的 package.json 中未声明依赖项

修复方法：

bun add <package> --cwd <workspace>

问题：存在多个锁文件

原因： 在工作区目录中运行 bun install

修复方法：

rm apps/*/bun.lockb packages/*/bun.lockb
bun install  # From root only

问题：版本冲突

原因： 不同工作区中的同一软件包使用了不同版本

修复方法： 使用依赖项目录：

{
  "catalog": {
    "problematic-package": "^1.0.0"
  }
}

验证输出

示例报告请参见 references/full-guide.md（§ 验证输出示例）。

最佳实践

• 始终使用工作区协议："@myorg/shared": "workspace:*"
• 使用 --cwd 执行工作区操作：bun add lodash --cwd apps/web（不要使用 cd apps/web && bun add）
• 仅从根目录运行 bun install——保持单一锁文件
• 使用依赖项目录共享版本（参见上文 § 依赖项目录）
• 在每个工作区显式声明所有依赖项——不要依赖提升机制

CI/CD 集成

# .github/workflows/validate.yml
- name: Validate Bun Workspace
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

集成

• linter-formatter-init - 使用 Bun 配置 Biome
• project-init-orchestrator - 创建工作区结构
• nextjs-validator - 验证工作区中的 Next.js