命令参考

所有 PCU 命令和选项的完整参考。了解每个命令、标志和可用的配置选项。

命令概览

PCU 提供几个主要命令，既有全名也有便捷的简写：

特殊快捷方式

pcu init - 初始化工作空间

初始化完整的 PNPM 工作空间环境和 PCU 配置。

pcu init
pcu i

选项

配置模板

PCU 为常见项目类型提供预配置的模板：

模板类型

• minimal - 仅包含基本设置的简单配置
• standard - 适合大多数项目的平衡配置
• full - 包含所有可用选项的全面配置
• monorepo - 为大型单体仓库优化，具备高级功能
• enterprise - 企业级，具备安全和治理功能

# 使用简单模板
pcu init --template minimal

# 企业单体仓库设置
pcu init --template enterprise --interactive

# React 项目与 TypeScript
pcu init --template standard --react --typescript

交互式配置向导

交互式模式（--interactive）提供引导式设置体验：

向导功能

• 项目检测：自动检测项目类型（React、Vue、TypeScript）
• 工作空间结构：发现现有包并建议最优配置
• 包规则设置：交互式选择包规则和更新策略
• 注册表配置：设置自定义 NPM 注册表和身份验证
• 性能调优：根据项目大小和需求优化设置
• 主题选择：选择颜色主题和进度条样式
• 验证设置：配置质量门和安全检查

创建的文件和目录

核心文件

目录结构

模板特定文件

使用示例

快速开始

pcu init

使用自动项目检测的标准模板初始化。

交互式设置

pcu init --interactive

启动完整的配置向导，提供引导式设置。

单体仓库初始化

pcu init --template monorepo --typescript --verbose

创建企业级单体仓库，支持 TypeScript 并显示详细输出。

pcu check - 检查更新

检查 pnpm 工作空间目录中的过时依赖。

pcu check
pcu -c
pcu chk

选项

输出格式

• table：带颜色和详细信息的丰富表格格式
• minimal：简单的 npm-check-updates 风格（package → version）
• json：用于程序化使用的 JSON 输出
• yaml：用于配置文件的 YAML 输出

pcu update - 更新依赖

将目录依赖更新到新版本。

pcu update --interactive
pcu -u -i

选项

交互式功能

交互式模式（--interactive 或 -i）提供高级包选择功能：

包选择界面

• 多选：使用复选框选择单个包更新
• 搜索功能：按名称或描述过滤包
• 批量操作：选择/取消选择多个包
• 更新策略选择：为每个包选择更新策略（latest、greatest、minor、patch）

智能冲突解决

• 对等依赖检测：提供解决建议
• 破坏性更改警告：基于语义版本分析
• 影响分析：显示受影响的工作空间包
• 回滚功能：如果更新导致问题可回滚

高级更新策略

# 仅补丁和小版本更新
pcu update --target minor --confirm-major

使用示例

安全交互式更新

pcu update --interactive --create-backup --target minor

交互式更新依赖，自动备份，仅限于小版本增量。

生产安全更新

pcu update --exclude "*-dev" --confirm-major --dry-run

显示生产依赖项中将被更新的内容，主版本更新需要确认。

框架特定更新

pcu update --include "react*,@types/*" --prerelease

更新 React 生态系统包，包括 TypeScript 定义，允许预发布版本。

pcu analyze - 影响分析

分析更新特定依赖的影响。

pcu analyze default react
pcu a default react 18.3.0
pcu -a react17 @types/react

参数

pcu workspace - 工作空间信息

显示工作空间信息和验证。

pcu workspace
pcu -s

选项

pcu theme - 主题配置

配置颜色主题和 UI 外观。

pcu theme --list
pcu -t --set modern
pcu theme --interactive

选项

可用主题

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

使用示例

列出可用主题

pcu theme --list

显示所有可用主题及其描述。

直接设置主题

pcu theme --set modern
pcu -t --set neon

直接设置指定主题。

交互式主题配置

pcu theme --interactive
pcu -t -i

启动引导式主题选择向导，允许您预览主题并交互式配置 UI 设置。

全局选项

这些选项适用于所有命令：

pcu security - 安全漏洞扫描

使用 npm audit 和可选的 Snyk 集成进行全面的安全漏洞扫描，具备自动修复功能。

pcu security
pcu sec

选项

安全报告功能

安全命令提供全面的漏洞分析：

• 多扫描器集成：结合 npm audit 和 Snyk 进行全面覆盖
• 严重程度分类：将漏洞分类为 critical、high、moderate、low 和 info
• 自动修复：使用 --fix-vulns 自动应用安全补丁
• 包建议：建议特定版本更新以解决漏洞
• 开发依赖：可选择包含或排除开发依赖
• CWE/CVE 信息：详细的漏洞标识符和描述
• 退出代码：返回适当的代码（0 表示清洁，1 表示发现漏洞）
• CI/CD 就绪：JSON 输出和非交互模式用于自动化

使用示例

基础漏洞扫描

pcu security

使用 npm audit 执行标准安全扫描，在格式化表格中显示结果。

自动修复扫描

pcu security --fix-vulns

扫描漏洞并自动应用可用的安全修复。

高严重程度过滤

pcu security --severity high

仅显示高严重程度和关键严重程度的漏洞，过滤掉低优先级问题。

使用 Snyk 的全面扫描

pcu security --snyk --include-dev --verbose

运行 npm audit 和 Snyk 扫描，包括开发依赖项，显示详细的漏洞信息。

CI/CD 管道集成

pcu security --format json --severity critical --no-color > security-report.json

将关键安全漏洞导出为 JSON 格式，用于 CI/CD 管道中的自动化处理。

生产环境自动修复

pcu security --auto-fix --severity moderate --exclude-dev

自动修复生产依赖项中中等及更高严重程度的漏洞。

安全工作流集成

部署前安全检查

# 如果存在关键漏洞则构建失败
pcu security --severity critical
if [ $? -ne 0 ]; then
  echo "发现关键安全漏洞。构建失败。"
  exit 1
fi

自动化安全维护

# 每周安全维护
pcu security --fix-vulns --severity moderate --create-backup

全局选项

这些选项适用于所有命令，可以通过环境变量设置：

环境变量使用

所有全局选项都可以通过环境变量配置：

# 全局设置工作空间
export PCU_WORKSPACE="/path/to/workspace"

# 默认启用详细日志
export PCU_VERBOSE=true

# 使用企业注册表
export PCU_REGISTRY="https://npm.company.com/"

# 为慢网络增加超时时间
export PCU_TIMEOUT=60000

# 使用自定义配置
export PCU_CONFIG="/etc/pcu/config.json"

环境变量详细配置

核心环境变量

命令特定环境变量

主题和显示环境变量

安全和缓存环境变量

高级配置环境变量

环境变量示例

# 启用全功能的开发设置
export PCU_WORKSPACE="./my-workspace"
export PCU_VERBOSE=true
export PCU_THEME="modern"
export PCU_PROGRESS_STYLE="fancy"
export PCU_INTERACTIVE=true
export PCU_CREATE_BACKUP=true

配置优先级

设置按以下顺序应用（后面的会覆盖前面的）：

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

交互式功能和进度跟踪

PCU 提供先进的交互功能和复杂的进度跟踪，贯穿所有命令。

交互式命令界面

包选择系统

• 智能多选：使用视觉复选框和键盘快捷键选择特定包
• 搜索和过滤：实时包过滤，支持模式匹配和模糊搜索
• 批量操作：通过基于类别的选择来选择/取消选择整个组
• 影响预览：在应用任何更新之前查看潜在变化

配置向导

交互式配置向导（pcu init --interactive）提供：

• 工作空间检测：自动发现现有 PNPM 工作空间
• 模板选择：在最小和完整配置模板之间选择
• 包规则设置：为不同包类别配置规则（React、Vue、TypeScript）
• 注册表配置：设置自定义 NPM 注册表和身份验证
• 验证设置：配置质量门和安全检查

目录和文件浏览器

• 工作空间导航：内置文件系统浏览器用于工作空间选择
• 路径验证：实时验证工作空间路径和结构
• 预览模式：在确认选择之前查看工作空间内容

高级进度跟踪

多样式进度条

PCU 提供六种不同的进度条样式，可以按命令或全局配置：

# 使用渐变进度条
pcu update --progress-style gradient

# 彩虹动画进度
pcu check --progress-style rainbow

# CI/CD 环境的最小样式
pcu security --progress-style minimal

进度功能

• 多步骤跟踪：显示不同阶段的进度（扫描 → 分析 → 更新）
• 并行操作状态：为并发操作提供单独的进度条
• 性能指标：实时速度指示器、预计时间、经过时间
• 内存安全显示：稳定的多行输出，减少终端闪烁

批处理状态

• 队列管理：显示待处理、活跃和已完成的包操作
• 冲突解决：交互式处理对等依赖冲突
• 错误恢复：为失败操作提供跳过/重试选项和详细错误上下文
• 回滚功能：如果在更新期间检测到问题，可以撤消更改

错误处理和恢复

智能错误检测

• 验证错误：预检查并为常见错误提供有用建议
• 网络问题：注册表故障的指数退避自动重试
• 依赖冲突：详细的冲突分析和解决建议
• 权限问题：文件系统权限问题的清晰指导

交互式恢复选项

• 跳过并继续：跳过有问题的包并继续其余更新
• 使用选项重试：使用不同参数重试失败的操作
• 回滚更改：如果批量操作期间出现问题，撤消部分更改
• 导出错误报告：生成详细的错误报告用于故障排除

工作空间集成

自动发现功能

• PNPM 工作空间检测：自动查找和验证工作空间配置
• 目录发现：检测现有目录及其包映射
• 包分析：分析工作空间结构和依赖关系
• 配置继承：自动应用特定于工作空间的设置

验证和健康检查

• 结构验证：确保工作空间遵循 PNPM 最佳实践
• 依赖一致性：检查跨包的版本不匹配
• 配置完整性：根据工作空间结构验证 PCU 配置
• 健康指标：提供全面的工作空间健康评估

使用示例

具有高级功能的交互式更新

pcu update --interactive --progress-style fancy --batch-size 15

使用华丽的进度条和优化的批处理启动交互式更新。

带预览的配置

pcu init --interactive --preview --verbose

运行带预览模式和详细日志的配置向导。

错误恢复工作流

pcu update --interactive --create-backup --confirm-major

具有交互式错误恢复、自动备份和主要版本确认的更新。

自动更新系统

PCU 包含一个复杂的自动更新机制，使 CLI 工具保持最新的功能和安全补丁。

自动更新检查

默认情况下，PCU 在运行任何命令时检查更新：

# PCU 自动检查更新
pcu check
# 输出可能包含："📦 PCU v0.8.0 可用 (当前版本：v0.7.15)"

更新行为

CI/CD 环境检测

PCU 自动检测 CI/CD 环境并跳过更新检查以避免中断自动化管道：

• GitHub Actions：通过 GITHUB_ACTIONS 环境变量检测
• CircleCI：通过 CIRCLECI 环境变量检测
• Jenkins：通过 JENKINS_URL 环境变量检测
• GitLab CI：通过 GITLAB_CI 环境变量检测
• Azure DevOps：通过 TF_BUILD 环境变量检测
• 通用 CI：通过 CI 环境变量检测

更新安装

PCU 支持多个包管理器，具有自动回退功能：

# PCU 按顺序尝试：npm → pnpm → yarn
npm install -g pcu@latest
# 如果 npm 失败，尝试：
pnpm add -g pnpm-catalog-updates@latest
# 如果 pnpm 失败，尝试：
yarn global add pnpm-catalog-updates@latest

配置选项

环境变量

配置文件设置

{
  "updates": {
    "checkForUpdates": true,
    "autoUpdate": false,
    "checkInterval": 86400000,
    "timeout": 5000,
    "skipInCI": true,
    "notifyPrerelease": false
  }
}

更新通知

标准通知

pcu check
# ✨ PCU v0.8.0 可用 (当前版本：v0.7.15)
# 运行 'npm install -g pcu@latest' 以更新
# 使用 --no-update-check 禁用此消息

安全更新通知

pcu security
# 🔒 安全更新：PCU v0.7.16 包含安全修复 (当前版本：v0.7.15)
# 立即更新：npm install -g pcu@latest

预发布通知

# 仅在 notifyPrerelease: true 时显示
pcu check
# 🧪 PCU v0.8.0-beta.1 可用于测试 (当前版本：v0.7.15)
# 使用以下命令安装：npm install -g pcu@beta

手动更新命令

# 检查当前版本和可用更新
pcu --version
pcu -V

更新故障排除

更新检查失败

# 如果由于网络问题更新检查失败
PCU_UPDATE_TIMEOUT=10000 pcu check

# 即使在 CI 中也强制更新检查
PCU_SKIP_VERSION_CHECK=false CI=false pcu check

清除缓存

# 清除更新检查缓存
rm -rf ~/.pcu/cache/version-check

# 或完全禁用缓存
PCU_CACHE_ENABLED=false pcu check

权限问题

# 修复 npm 权限问题
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# 或使用处理权限更好的 pnpm/yarn
pnpm add -g pnpm-catalog-updates@latest

缓存管理系统

PCU 包含一个全面的缓存系统来优化性能并减少网络请求。

缓存类型

注册表缓存

存储 NPM 包元数据和版本信息：

• 默认 TTL：1小时（3,600,000毫秒）
• 最大大小：每种缓存类型10MB
• 最大条目数：500个包
• 磁盘持久化：启用

工作空间缓存

存储工作空间配置和 package.json 解析结果：

• 默认 TTL：5分钟（300,000毫秒）
• 最大大小：5MB
• 最大条目数：200个工作空间
• 磁盘持久化：禁用（仅内存）

缓存配置

环境变量

配置文件设置

{
  "cache": {
    "enabled": true,
    "ttl": 3600000,
    "maxSize": 52428800,
    "maxEntries": 10000,
    "persistToDisk": true,
    "cacheDir": "~/.pcu/cache",
    "registry": {
      "ttl": 3600000,
      "maxSize": 10485760,
      "maxEntries": 500
    },
    "workspace": {
      "ttl": 300000,
      "maxSize": 5242880,
      "maxEntries": 200,
      "persistToDisk": false
    }
  }
}

缓存管理命令

# 查看缓存统计信息（通过详细模式）
pcu check --verbose
# 显示：缓存命中率：85%，大小：15.2MB，条目数：342

缓存性能

优化功能

• LRU 淘汰：最少使用的项目首先被移除
• 自动清理：过期条目每5分钟清理一次
• 大小监控：超过大小限制时自动淘汰
• 并行处理：缓存操作不会阻塞主线程

性能优势

• 注册表请求：NPM 注册表调用减少60-90%
• 工作空间解析：重复运行时工作空间分析快80-95%
• 网络依赖：减少对网络连接的依赖
• 启动时间：后续操作启动时间快2-5倍