配置

配置 PCU 以匹配您的工作流和项目需求。了解配置文件、包特定规则和高级设置。

配置文件类型

PCU 支持多种配置文件格式和位置以适应不同的开发工作流。

支持的配置文件

PCU 按以下顺序搜索配置文件（找到第一个生效）：

Name
.pcurc.json
Type
JSON
Description
项目根目录中的主要 JSON 配置文件
Name
.pcurc.js
Type
JavaScript
Description
支持动态配置的 JavaScript 配置文件
Name
pcu.config.js
Type
JavaScript
Description
替代的 JavaScript 配置文件名
Name
~/.pcurc.json
Type
JSON
Description
主目录中的全局用户配置
Name
package.json
Type
JSON
Description
package.json 中的 "pcu" 键下的配置

JavaScript 配置支持

JavaScript 配置文件支持基于环境、工作空间结构或其他运行时条件的动态配置：

module.exports = {
  defaults: {
    target: process.env.NODE_ENV === 'production' ? 'minor' : 'latest',
    createBackup: true,
  },
  workspace: {
    autoDiscover: true,
    catalogMode: 'strict',
  },
  // 基于工作空间结构的动态包规则
  packageRules: [
    {
      patterns: ['react*'],
      target: 'minor',
      requireConfirmation: process.env.CI !== 'true',
    },
  ],
  // 环境特定配置
  ...(process.env.NODE_ENV === 'development' && {
    ui: {
      theme: 'modern',
      progressBarStyle: 'fancy',
    },
  }),
};

Package.json 配置

对于简单项目，配置可以嵌入到 package.json 中：

{
  "name": "my-project",
  "pcu": {
    "defaults": {
      "target": "minor",
      "createBackup": true
    },
    "packageRules": [
      {
        "patterns": ["@types/*"],
        "target": "latest",
        "autoUpdate": true
      }
    ]
  }
}

配置验证

PCU 自动验证配置文件并为常见问题提供详细的错误消息：

验证功能

JSON 模式验证：确保所有配置属性有效
模式验证：验证通配符模式和包名称格式
类型检查：验证所有配置值的正确数据类型
冲突检测：识别冲突的规则和配置选项
建议系统：为修复配置错误提供有用建议

验证示例

# 验证当前配置
pcu workspace --validate

# 常见验证错误及建议：
# ❌ packageRules[0] 中无效的目标 "lastest"
#    💡 您是否想要 "latest"？
#
# ❌ 模式 "react+" 是无效的通配符语法
#    💡 使用 "react*" 匹配以 "react" 开头的包
#
# ⚠️  包 "react" 存在冲突规则
#    📝 索引 0 和 2 的规则都匹配此包

{
  "defaults": {
    "target": "latest",
    "timeout": 30000,
    "parallel": 5
  },
  "workspace": {
    "autoDiscover": true,
    "catalogMode": "strict"
  },
  "output": {
    "format": "table",
    "color": true,
    "verbose": false
  }
}

包过滤

使用包含/排除模式和包特定规则控制要更新的包。

{
  "exclude": ["typescript", "@types/node", "react", "react-dom"],
  "include": ["lodash*", "chalk", "commander"]
}

包规则属性

Name
patterns
Type
string[]
Description
匹配包名称的通配符模式
Name
target
Type
enum
Description
更新目标：latest、greatest、minor、patch、newest
Name
requireConfirmation
Type
boolean
Description
更新这些包前总是询问
Name
autoUpdate
Type
boolean
Description
无需确认自动更新
Name
relatedPackages
Type
string[]
Description
遵循相同更新策略的包
Name
groupUpdate
Type
boolean
Description
将相关包一起更新

安全配置

配置安全漏洞扫描和自动修复。

{
  "security": {
    "autoFixVulnerabilities": true,
    "allowMajorForSecurity": true,
    "notifyOnSecurityUpdate": true
  }
}

Name
autoFixVulnerabilities
Type
boolean
Description
自动检查和修复安全漏洞
Name
allowMajorForSecurity
Type
boolean
Description
允许安全修复的主版本升级
Name
notifyOnSecurityUpdate
Type
boolean
Description
安全更新时显示通知

高级设置

使用高级配置选项微调性能和行为。

{
  "advanced": {
    "concurrency": 5,
    "timeout": 30000,
    "retries": 3,
    "cacheValidityMinutes": 60,
    "checkForUpdates": true
  }
}

Name
concurrency
Type
number
Description
并发网络请求数量
Name
timeout
Type
number
Description
网络请求超时时间（毫秒）
Name
retries
Type
number
Description
失败时重试次数
Name
cacheValidityMinutes
Type
number
Description
缓存有效期（设为 0 禁用缓存）
Name
checkForUpdates
Type
boolean
Description
启动时自动检查PCU工具更新。在CI环境中会跳过检查。有新版本时会显示更新通知和安装说明。

UI 配置

自定义视觉外观和用户界面设置。

{
  "ui": {
    "theme": "modern",
    "progressBars": true,
    "progressBarStyle": "gradient",
    "animations": true
  },
  "output": {
    "format": "table",
    "color": true,
    "verbose": false
  }
}

可用主题

default - 通用使用的平衡颜色
modern - 开发环境的活泼颜色
minimal - 生产环境的简洁风格
neon - 演示的高对比度颜色

进度条样式

PCU 支持 6 种不同的进度条样式，为操作期间提供增强的视觉反馈：

default - 基本样式的标准进度条
gradient - 现代外观的渐变色进度条
fancy - 带装饰元素的增强进度条
minimal - 简洁的进度指示器
rainbow - 活泼显示的多彩进度条
neon - 匹配霓虹主题的高对比度进度条

配置示例：

{
  "ui": {
    "theme": "modern",
    "progressBars": true,
    "progressBarStyle": "gradient"
  }
}

命令行使用：

pcu check --progress-style fancy
pcu update --progress-style rainbow
pcu security --progress-style neon

配置优先级

配置设置按以下优先级顺序应用：

命令行标志（最高优先级）
.pcurc.json 中的包特定规则
.pcurc.json 中的常规设置
默认值（最低优先级）

相关包自动继承其父包规则的设置，确保生态系统包间的版本一致性。

示例

React 生态系统

{
  "packageRules": [
    {
      "patterns": ["react", "react-dom"],
      "target": "minor",
      "requireConfirmation": true,
      "relatedPackages": ["@types/react", "@types/react-dom", "react-router-dom"]
    }
  ]
}

TypeScript 项目

{
  "packageRules": [
    {
      "patterns": ["typescript"],
      "target": "minor",
      "requireConfirmation": true
    },
    {
      "patterns": ["@types/*"],
      "target": "latest",
      "autoUpdate": true
    }
  ]
}

企业设置

{
  "defaults": {
    "target": "minor",
    "createBackup": true
  },
  "security": {
    "autoFixVulnerabilities": true,
    "allowMajorForSecurity": true
  },
  "ui": {
    "theme": "minimal",
    "progressBars": true,
    "progressBarStyle": "minimal"
  },
  "advanced": {
    "concurrency": 3,
    "timeout": 60000
  },
  "exclude": ["typescript", "@types/node", "react", "react-dom"]
}

环境变量

所有 CLI 选项都可以通过环境变量进行配置，以适应自动化和 CI/CD 环境：

# 工作空间设置
export PCU_WORKSPACE="/path/to/workspace"
export PCU_VERBOSE=true
export PCU_NO_COLOR=true

# 注册表配置
export PCU_REGISTRY="https://npm.company.com/"
export PCU_TIMEOUT=30000

# 配置文件
export PCU_CONFIG="/path/to/.pcurc.json"

环境变量优先级

配置源按以下顺序加载（后者覆盖前者）：

内置默认值（最低优先级）
全局配置（~/.pcurc.json）
项目配置（.pcurc.json）
环境变量（PCU_*）
命令行标志（最高优先级）

注册表配置

PCU 自动读取 NPM 和 PNPM 配置文件的注册表设置：

# 默认注册表
registry=https://registry.npmjs.org/

# 作用域注册表
@mycompany:registry=https://npm.mycompany.com/
@types:registry=https://registry.npmjs.org/

# 认证令牌
//npm.mycompany.com/:_authToken=${NPM_TOKEN}
//registry.npmjs.org/:_authToken=${NPM_PUBLIC_TOKEN}

# 传统认证（如果需要）
//npm.mycompany.com/:username=myuser
//npm.mycompany.com/:_password=base64encodedpassword
//npm.mycompany.com/:email=user@company.com

# SSL 和代理设置
strict-ssl=true
ca=/path/to/ca.pem
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080

注册表优先级

CLI --registry 标志（最高优先级）
PCU 配置（.pcurc.json 注册表部分）
项目 .npmrc/.pnpmrc
全局 .npmrc/.pnpmrc
默认 NPM 注册表（最低优先级）

增强缓存配置

PCU 包含先进的缓存系统以提高性能：

{
  "cache": {
    "enabled": true,
    "ttl": 3600000,
    "maxSize": 52428800,
    "maxEntries": 10000,
    "persistToDisk": true,
    "cacheDir": "~/.pcu/cache",
    "strategy": "lru"
  }
}

缓存设置

Name
enabled
Type
boolean
Description
启用/禁用缓存系统
Name
ttl
Type
number
Description
生存时间（毫秒）（默认1小时）
Name
maxSize
Type
number
Description
最大缓存大小（字节）（默认50MB）
Name
maxEntries
Type
number
Description
最大缓存条目数
Name
persistToDisk
Type
boolean
Description
在运行之间将缓存保存到磁盘
Name
cacheDir
Type
string
Description
持久缓存存储目录
Name
strategy
Type
enum
Description
缓存驱逐策略：lru、fifo、lfu

验证配置

PCU 包含带有有用建议的全面验证：

{
  "validation": {
    "strict": true,
    "warnOnRiskyUpdates": true,
    "requireConfirmationFor": ["major"],
    "suggestions": {
      "enabled": true,
      "includePerformanceTips": true,
      "includeBestPractices": true
    }
  }
}

验证选项

Name
strict
Type
boolean
Description
启用带有附加检查的严格验证模式
Name
warnOnRiskyUpdates
Type
boolean
Description
对潜在风险更新显示警告
Name
requireConfirmationFor
Type
array
Description
需要确认的更新类型：major、minor、patch
Name
suggestions.enabled
Type
boolean
Description
启用有用的建议和提示
Name
suggestions.includePerformanceTips
Type
boolean
Description
包含性能优化建议
Name
suggestions.includeBestPractices
Type
boolean
Description
包含最佳实践建议

交互模式配置

配置交互式提示和用户体验：

{
  "interactive": {
    "enabled": true,
    "pageSize": 15,
    "showPackageDescriptions": true,
    "showReleaseNotes": false,
    "autoComplete": {
      "enabled": true,
      "fuzzyMatching": true,
      "maxSuggestions": 10
    },
    "confirmations": {
      "majorUpdates": true,
      "forceUpdates": true,
      "multiplePackages": false
    }
  }
}

交互设置

Name
enabled
Type
boolean
Description
启用交互模式功能
Name
pageSize
Type
number
Description
列表中每页显示的项目数
Name
showPackageDescriptions
Type
boolean
Description
在选择列表中显示包描述
Name
showReleaseNotes
Type
boolean
Description
显示更新的发布说明（需要网络）
Name
autoComplete.enabled
Type
boolean
Description
启用包名称自动完成
Name
autoComplete.fuzzyMatching
Type
boolean
Description
启用自动完成的模糊匹配
Name
confirmations.majorUpdates
Type
boolean
Description
主版本更新需要确认

Monorepo 配置

PCU 为大型 monorepo 和复杂工作空间管理提供专门设计的高级功能。

版本同步

在您的 monorepo 中保持相关包的同步：

{
  "monorepo": {
    "syncVersions": {
      "enabled": true,
      "groups": [
        {
          "name": "react-ecosystem",
          "packages": ["react", "react-dom", "@types/react", "@types/react-dom"],
          "strategy": "exact" // 或 "compatible", "latest"
        },
        {
          "name": "testing-libraries",
          "packages": ["jest", "@testing-library/*", "@types/jest"],
          "strategy": "compatible"
        }
      ]
    },
    "catalogPriority": ["default", "react17", "node18"],
    "crossWorkspaceDependencies": {
      "analyze": true,
      "enforce": "warn" // "error", "warn", "off"
    }
  }
}

高级工作空间管理

目录优先级系统

定义冲突出现时哪些目录优先：

{
  "catalogPriority": ["production", "default", "experimental"],
  "catalogConflictResolution": "priority" // 或 "interactive", "error"
}

跨工作空间依赖

分析和管理工作空间包之间的依赖关系：

Name
analyze
Type
boolean
Description
分析跨工作空间依赖关系
Name
enforce
Type
enum
Description
如何处理版本不匹配：error、warn、off
Name
reportUnused
Type
boolean
Description
报告目录中未被任何工作空间包使用的包
Name
validateVersions
Type
boolean
Description
验证所有工作空间包都使用目录版本

Monorepo 特定包规则

为您的 monorepo 的不同区域创建复杂的规则：

{
  "packageRules": [
    {
      "name": "前端包",
      "patterns": ["react*", "@types/react*", "next*"],
      "workspacePackages": ["apps/web", "apps/admin"],
      "target": "minor",
      "groupUpdate": true,
      "requireConfirmation": true
    },
    {
      "name": "后端依赖",
      "patterns": ["express*", "@types/express*", "fastify*"],
      "workspacePackages": ["apps/api", "services/*"],
      "target": "patch",
      "autoUpdate": false
    },
    {
      "name": "开发工具",
      "patterns": ["eslint*", "prettier", "typescript"],
      "workspacePackages": ["*"], // 所有包
      "target": "latest",
      "autoUpdate": true,
      "excludeFromProduction": true
    }
  ]
}

工作空间特定配置

为您的 monorepo 的不同部分使用不同的配置：

{
  "workspaceRules": {
    "apps/web": {
      "defaults": {
        "target": "minor",
        "createBackup": true
      },
      "packageRules": [
        {
          "patterns": ["react*"],
          "target": "patch"
        }
      ]
    },
    "packages/*": {
      "defaults": {
        "target": "latest",
        "requireConfirmation": false
      }
    },
    "tools/*": {
      "defaults": {
        "target": "latest",
        "autoUpdate": true
      }
    }
  }
}

大型 Monorepo 的性能优化

批处理配置

Name
batchSize
Type
number
Description
每批处理的包数量
Name
concurrency
Type
number
Description
最大并发操作数
Name
cacheWorkspaceStructure
Type
boolean
Description
在运行之间缓存工作空间包发现
Name
parallelCatalogProcessing
Type
boolean
Description
并行处理多个目录

内存管理

{
  "monorepo": {
    "memoryOptimization": {
      "streamingMode": true, // 处理包而不将所有包加载到内存
      "maxMemoryUsage": "2GB", // 大型工作空间的内存限制
      "temporaryFileCleanup": "immediate" // "immediate", "session-end", "manual"
    }
  }
}

Monorepo 验证

复杂工作空间设置的全面验证：

验证规则

Name
enforceWorkspaceProtocol
Type
boolean
Description
确保内部依赖使用 workspace: 协议
Name
validateCatalogCoverage
Type
boolean
Description
确保所有依赖都被目录覆盖
Name
requireConsistentVersions
Type
boolean
Description
要求所有工作空间包对共享依赖使用相同版本
Name
detectCircularDependencies
Type
boolean
Description
检测工作空间包之间的循环依赖

Monorepo 使用示例

大型企业 Monorepo 设置

{
  "monorepo": {
    "syncVersions": {
      "enabled": true,
      "groups": [
        {
          "name": "core-frontend",
          "packages": ["react", "react-dom", "react-router", "@types/react*"],
          "strategy": "exact"
        },
        {
          "name": "ui-libraries",
          "packages": ["@company/design-system", "@company/components"],
          "strategy": "workspace"
        }
      ]
    },
    "performance": {
      "batchSize": 100,
      "concurrency": 20,
      "streamingMode": true
    },
    "workspaceRules": {
      "apps/*": { "target": "minor", "requireConfirmation": true },
      "packages/*": { "target": "latest", "autoUpdate": true },
      "tools/*": { "target": "latest", "autoUpdate": true }
    }
  }
}

CI/CD 优化配置

{
  "monorepo": {
    "ci": {
      "parallelCatalogProcessing": true,
      "skipInteractivePrompts": true,
      "generateReport": true,
      "reportFormat": "json",
      "exitOnError": true
    },
    "validation": {
      "enforceWorkspaceProtocol": true,
      "validateCatalogCoverage": true,
      "failOnInconsistentVersions": true
    }
  }
}