syncpack-version-groups

用途

syncpack-version-groups 用于在 monorepo 中定义复杂的依赖版本策略。它通过 syncpack 的 versionGroups 配置，对不同的依赖、依赖类型、包和版本说明符格式进行分组，并施加统一的版本管理规则。

主要能力

版本组结构

每个版本组是一个对象，包含过滤条件和策略选项：

export default {
  versionGroups: [
    {
      label: 'Description of this group',
      dependencies: ['package-name', '@scope/**'],
      dependencyTypes: ['prod', 'dev'],
      packages: ['apps/**'],
      specifierTypes: ['exact', 'range'],
      // Policy options (choose one)
      preferVersion: 'highestSemver',
      // pinVersion: '1.0.0',
      // isBanned: true,
      // isIgnored: true,
    },
  ],
};

过滤选项

dependencies：按名称或 glob 匹配特定包，例如 'react'、'react-*'、'@types/**'、'{react,vue}'。
dependencyTypes：按依赖出现的位置过滤，可选值包括 dev、local、overrides、peer、pnpmOverrides、prod、resolutions。
packages：按 package.json 文件过滤，例如 'apps/**'、'packages/core'、'!packages/legacy'。
specifierTypes：按版本说明符格式过滤，可选值包括 exact、range、tag、url、file、workspace。

版本策略

preferVersion：当存在版本不一致时选择哪个版本胜出。可选 'highestSemver'、'lowestSemver'、指定包名（如 'packages/core'）或 'local'。
pinVersion：强制所有匹配项使用指定版本，例如 pinVersion: '5.3.3'。
isBanned：禁止使用某些包，例如 isBanned: true。
isIgnored：将匹配项排除在版本检查之外，例如 isIgnored: true。

使用方式

常见模式

Monorepo 单一版本策略：忽略本地工作区包，其余使用最高版本。

export default {
  versionGroups: [
    {
      label: 'Ignore local workspace packages',
      dependencyTypes: ['local'],
      isIgnored: true,
    },
    {
      label: 'Use highest version for everything else',
      preferVersion: 'highestSemver',
    },
  ],
};

框架版本固定：跨所有包固定 React 版本。

export default {
  versionGroups: [
    {
      label: 'Pin React version across all packages',
      dependencies: ['react', 'react-dom', '@types/react', '@types/react-dom'],
      pinVersion: '18.2.0',
    },
  ],
};

应用与库使用不同规则：应用可任意版本，库必须一致。

export default {
  versionGroups: [
    {
      label: 'Apps can have any version',
      packages: ['apps/**'],
      isIgnored: true,
    },
    {
      label: 'Libraries must have consistent versions',
      packages: ['packages/**'],
      preferVersion: 'highestSemver',
    },
  ],
};

禁用存在安全漏洞的包：

export default {
  versionGroups: [
    {
      label: 'Ban packages with known vulnerabilities',
      dependencies: [
        'lodash', // use lodash-es instead
        'moment', // use date-fns instead
        'request', // use axios/fetch instead
      ],
      isBanned: true,
    },
  ],
};

对等依赖灵活性：忽略 peer 依赖，严格管理 prod/dev。

export default {
  versionGroups: [
    {
      label: 'Allow peer dependency flexibility',
      dependencyTypes: ['peer'],
      isIgnored: true,
    },
    {
      label: 'Strict versions for prod/dev',
      dependencyTypes: ['prod', 'dev'],
      preferVersion: 'highestSemver',
    },
  ],
};

作用域包归属：指定某个包作为版本来源。

export default {
  versionGroups: [
    {
      label: 'Core team owns @myorg/core',
      dependencies: ['@myorg/core'],
      preferVersion: 'packages/core',
    },
    {
      label: 'UI team owns @myorg/ui-*',
      dependencies: ['@myorg/ui-*'],
      preferVersion: 'packages/ui',
    },
  ],
};

CLI 命令

# List all version mismatches
npx syncpack list-mismatches

# Fix version mismatches
npx syncpack fix

# Only fix specific dependencies
npx syncpack fix --dependencies react

# Only fix specific dependency types
npx syncpack fix --dependency-types prod,peer

调试

使用标签并开启详细输出：

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

顺序很重要

版本组按顺序评估，第一个匹配的组生效：

export default {
  versionGroups: [
    // Specific rule first
    { dependencies: ['react'], pinVersion: '18.2.0' },
    // General rule second
    { preferVersion: 'highestSemver' },
  ],
};

适用场景

需要跨多个 package.json 统一依赖版本的 monorepo。
需要固定特定框架或库版本的项目。
需要禁止使用某些已弃用或存在安全风险的包。
需要对应用和库采用不同版本管理策略。
需要灵活处理对等依赖，同时严格管理生产与开发依赖。

限制

资料中未提供关于 syncpack 的安装要求、版本兼容性、性能影响或与其他工具的集成限制等信息。