名称: syncpack-version-groups 用户可调用: false 描述: 用于在 syncpack 中定义版本策略、禁止依赖、锁定版本或创建分区版本组。涵盖高级版本管理模式。允许的工具:

读取
写入
编辑
Bash
Grep
Glob

Syncpack 版本组

版本组允许您在 monorepo 中定义复杂的依赖版本策略。本技能涵盖高级版本管理模式。

版本组结构

export default {
  versionGroups: [
    {
      label: '描述此组',
      dependencies: ['包名称', '@作用域/**'],
      dependencyTypes: ['生产', '开发'],
      packages: ['应用/**'],
      specifierTypes: ['精确', '范围'],
      // 策略选项（选择一个）
      preferVersion: '最高语义版本',
      // pinVersion: '1.0.0',
      // isBanned: true,
      // isIgnored: true,
    },
  ],
};

过滤选项

dependencies

通过名称或通配符匹配特定包：

dependencies: [
  'react',           // 精确匹配
  'react-*',         // 通配符
  '@types/**',       // 作用域包
  '{react,vue}',     // 或逻辑
]

dependencyTypes

按依赖出现位置过滤：

dependencyTypes: [
  'dev',           // devDependencies
  'local',         // workspace: 协议
  'overrides',     // npm 覆盖
  'peer',          // peerDependencies
  'pnpmOverrides', // pnpm.overrides
  'prod',          // dependencies
  'resolutions',   // yarn 决议
]

packages

按 package.json 文件过滤：

packages: [
  'apps/**',      // 所有应用
  'packages/core', // 特定包
  '!packages/legacy', // 排除模式
]

specifierTypes

按版本说明符格式过滤：

specifierTypes: [
  'exact',        // 1.2.3
  'range',        // ^1.2.3, ~1.0.0, >=2.0.0
  'tag',          // latest, next, canary
  'url',          // https://, git://
  'file',         // file:../路径
  'workspace',    // workspace:*
]

版本策略

preferVersion

选择当版本不匹配时获胜的版本：

// 使用找到的最高语义版本
preferVersion: 'highestSemver'

// 使用找到的最低语义版本
preferVersion: 'lowestSemver'

// 使用特定包拥有的版本
preferVersion: 'packages/core'

// 使用本地工作区版本
preferVersion: 'local'

pinVersion

强制所有匹配项使用特定版本：

{
  label: '将 TypeScript 锁定到 LTS',
  dependencies: ['typescript'],
  pinVersion: '5.3.3',
}

isBanned

阻止使用某些包：

{
  label: '禁止已弃用的包',
  dependencies: ['moment', 'request'],
  isBanned: true,
}

isIgnored

从版本检查中排除：

{
  label: '忽略本地包',
  dependencyTypes: ['local'],
  isIgnored: true,
}

常见模式

单版本策略的 Monorepo

export default {
  versionGroups: [
    {
      label: '忽略本地工作区包',
      dependencyTypes: ['local'],
      isIgnored: true,
    },
    {
      label: '为其他所有项使用最高版本',
      preferVersion: 'highestSemver',
    },
  ],
};

框架锁定

export default {
  versionGroups: [
    {
      label: '在所有包中锁定 React 版本',
      dependencies: ['react', 'react-dom', '@types/react', '@types/react-dom'],
      pinVersion: '18.2.0',
    },
  ],
};

应用与库的不同规则

export default {
  versionGroups: [
    {
      label: '应用可以有任意版本',
      packages: ['apps/**'],
      isIgnored: true,
    },
    {
      label: '库必须具有一致的版本',
      packages: ['packages/**'],
      preferVersion: 'highestSemver',
    },
  ],
};

禁止安全漏洞

export default {
  versionGroups: [
    {
      label: '禁止已知漏洞的包',
      dependencies: [
        'lodash', // 使用 lodash-es 替代
        'moment', // 使用 date-fns 替代
        'request', // 使用 axios/fetch 替代
      ],
      isBanned: true,
    },
  ],
};

对等依赖的灵活性

export default {
  versionGroups: [
    {
      label: '允许对等依赖的灵活性',
      dependencyTypes: ['peer'],
      isIgnored: true,
    },
    {
      label: '生产/开发依赖的严格版本',
      dependencyTypes: ['prod', 'dev'],
      preferVersion: 'highestSemver',
    },
  ],
};

作用域包的所有权

export default {
  versionGroups: [
    {
      label: '核心团队拥有 @myorg/core',
      dependencies: ['@myorg/core'],
      preferVersion: 'packages/core',
    },
    {
      label: 'UI 团队拥有 @myorg/ui-*',
      dependencies: ['@myorg/ui-*'],
      preferVersion: 'packages/ui',
    },
  ],
};

CLI 命令用于版本组

# 列出所有版本不匹配
npx syncpack list-mismatches

# 修复版本不匹配
npx syncpack fix

# 仅修复特定依赖
npx syncpack fix --dependencies react

# 仅修复特定依赖类型
npx syncpack fix --dependency-types prod,peer

调试版本组

使用标签和详细输出运行：

npx syncpack list-mismatches --log-levels warn,error

顺序重要

版本组按顺序评估。第一个匹配的组获胜：

export default {
  versionGroups: [
    // 特定规则优先
    { dependencies: ['react'], pinVersion: '18.2.0' },
    // 通用规则其次
    { preferVersion: 'highestSemver' },
  ],
};