composer-upgrade

Composer 升级

升级工作流

升级 PHP 项目时，请遵循以下顺序：

1. 检查安全问题 → composer audit —— 这里的修复优先级最高
2. 识别哪些已过时 → composer outdated --format=json
3. 排定优先级 —— 同时存在 CVE 且已过时的包优先处理；参见 references/audit.md
4. 诊断阻碍项 → composer why-not vendor/package version —— 记录所有阻碍更新的子包
5. 追踪依赖关系 → composer why vendor/package
6. 更新包 → composer update vendor/package —— 若被阻碍，请一并包含已识别的阻碍项：composer update vendor/package blocker/one blocker/two
7. 测试
8. 收紧版本约束 → composer bump（仅限应用程序）
9. 重新审计 → composer audit，确认所有安全通告均已解决

完整的标志参考（包括用于非交互式运行的全局标志 --no-interaction --no-progress --no-ansi）请参见 references/commands.md。 详细策略（包括合并冲突解决）请参见 references/upgrade-workflow.md。 安全审计详情、严重程度分级以及如何构建按优先级排序的包列表，请参见 references/audit.md。

解决 composer.lock 合并冲突

当 composer.lock 出现合并冲突时，使用 scripts/diff_lock.py 比较双方并生成协调二者所需的命令。

在合并冲突进行中：

# Compare HEAD vs MERGE_HEAD automatically and output composer commands
python3 scripts/diff_lock.py --conflict

# Human-readable summary of what changed
python3 scripts/diff_lock.py --conflict --format=summary

比较任意两个分支或文件：

python3 scripts/diff_lock.py main:composer.lock feature-branch:composer.lock
python3 scripts/diff_lock.py HEAD:composer.lock MERGE_HEAD:composer.lock
python3 scripts/diff_lock.py old.lock new.lock

该脚本会输出 composer require / composer remove 命令，将包从源状态迁移到目标状态。运行生成的命令，然后提交结果。

完整的分步流程请参见 references/upgrade-workflow.md 中的 "Workflow: Merge Conflict in composer.lock"。

核心命令

完整的标志参考和版本约束速查请参见 references/commands.md。

composer outdated

composer outdated --format=json           # preferred when parsing output (fewer tokens)
composer outdated --direct --format=json  # only direct deps

红色 = 主版本更新（很可能有破坏性变更）。黄色 = 次版本/补丁版本（安全）。! = 不符合 semver 安全性。

composer why-not

composer why-not vendor/package 2.0      # what prevents this upgrade
composer why-not php 8.2                 # what blocks a PHP version bump

输出会显示依赖链：哪些包要求相互冲突的版本。

composer why

composer why vendor/package              # which installed packages depend on this one

composer update

composer update vendor/package --no-interaction --no-progress --no-ansi
composer update vendor/package --dry-run --no-interaction --no-ansi   # preview first

# If blocked, first identify which sub-dependencies are preventing the update:
composer why-not vendor/package 2.0
# Then include only those specific blockers in the update command:
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

常见模式

"为什么我无法更新 X？"

composer why-not vendor/package 3.0

阅读输出以找出是哪个包对其构成约束，然后检查该约束包自身是否可以更新。

"是什么阻碍了我的 PHP 版本升级？"

composer why-not php 8.2

列出所有缺少 php: ^8.2 约束的包，并按阻碍程度排序。

"安全的增量升级"

优先使用 --dry-run 先逐个更新直接依赖：

composer update vendor/package --dry-run --no-interaction --no-ansi
composer update vendor/package --no-interaction --no-progress --no-ansi

若被阻碍，使用 composer why-not 找出阻止更新的具体包，然后仅在更新命令中包含这些包：

composer why-not vendor/package 2.0
# → reveals blocker/one and blocker/two are preventing the update
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

提升主版本约束

优先使用 composer require 而非手动编辑 composer.json —— 它能在一步内更新约束并解析锁文件：

composer require vendor/package:"^3.0" --dry-run --no-interaction --no-ansi
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

对于有风险的升级（认证、权限、数据库层），使用双重约束在提交前进行测试：

# Allow both old and new major versions while testing
composer require vendor/package:"^2.5.0|^3.0" --no-interaction --no-progress --no-ansi
# If tests pass, lock in the new version:
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

更多细节请参见 references/upgrade-workflow.md 中的 "Techniques for Major Version Upgrades"。

升级后收紧约束（应用程序）

composer bump                  # raise lower bounds in composer.json to installed versions
composer bump --dev-only       # only require-dev (safe for libraries too)

之前："symfony/console": "^6.0" → 之后："symfony/console": "^6.4.3"（^ 被保留，因此未来的次版本/补丁版本升级仍然有效）。

自动 bump 配置和完整标志参考请参见 references/commands.md。

仅限应用程序：不要在库上运行 composer bump（不带 --dev-only）—— 它会以破坏下游使用者的方式收紧约束。