摆脱升级恐慌：掌握Composer语义化版本精准控制策略-composer-PHP中文网

composer精确安装指定版本的正确命令是composer require vendor/package:1.2.3，不加^或~符号才默认精确匹配；若误用^7.5.0则允许7.5.x升级，并非锁定7.5.0。

摆脱升级恐慌：掌握composer语义化版本精准控制策略

Composer 的版本控制不是“锁死就安全”，而是“约束得当才可控”。真正导致升级失控的，从来不是 ^ 或 ~ 本身，而是 composer.json 里的写法 + composer.lock 的状态 + CI/CD 中执行的命令这三者不一致。

命令行里不加任何符号，才是默认精确匹配。很多人输 composer require guzzlehttp/guzzle:^7.5.0 还以为锁死了 7.5.0，其实它允许所有 7.5.x —— 因为 ^7.5.0 就是 >=7.5.0 。

要锁定 7.5.0，就写 composer require guzzlehttp/guzzle:7.5.0（无前缀）
如果已经装了 ^7.5.0，先删掉 vendor/guzzlehttp/guzzle 和 composer.lock 中对应项，再重跑上面那条命令
执行后立刻检查 composer.lock：搜索包名，确认 "version": "7.5.0" 且 "source": {"reference": "..."} 是确定 commit hash，不是分支名或空值

写 "vendor/package": "dev-main" 只是告诉 Composer 去拉 main 分支当前 HEAD，下次 composer update 就可能换提交。这不是开发便利，是隐性风险。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

真要固定某次提交，必须用 dev-main#abc1234 格式（abc1234 是实际 commit hash）
分支名含斜杠（如 feature/login-flow）需 URL 编码为 feature%2Flogin-flow，否则解析失败
CI 构建中若用了 dev-main，建议加 --dry-run 预检：运行 composer update --dry-run，看输出里该包的 commit 是否变动
长期维护 fork 时，比 #hash 更可持续的做法是：在 repositories 里声明 VCS 源，并在 fork 的 composer.json 中设 "version": "1.2.3-patch1"，然后 require 写 "1.2.3-patch1"

常见现象：把 "monolog/monolog": "^2.8.0" 改成 "2.8.1"，跑 composer install 后还是 2.8.0 —— 因为 composer.lock 里还记着旧版本，而 install 只认 lock。

改完 composer.json 后，必须运行 composer update monolog/monolog（指定包）或全量 composer update，才能更新 lock 文件
CI 环境务必用 composer install，禁用 update；否则 lock 被绕过，依赖树重新计算，结果不可控
本地调试时怀疑版本不对，直接运行 composer show monolog/monolog，它读的是 vendor 下真实安装的版本，比看 json 更可靠
composer.lock 必须提交进 Git；被 .gitignore 掉、或有人手动删了再 install，就等于放弃版本契约

这些点不报错，但会让“稳定版本”在不同机器上悄悄漂移。

没设 "config": {"platform": {"php": "8.1.10"}}：本地 PHP 8.2 解析出的依赖，可能和生产 PHP 8.1 不同；platform 配置能强制 Composer 按目标环境选包
用了 --with-dependencies 却没检查间接依赖：执行 composer update foo/bar 时加这个参数，会连带更新它的子依赖——如果子依赖写了 dev-main，就可能被刷新
Git 分支被 force-push 或删除后，dev-feature/x 直接报 Could not find package ... at version dev-feature/x；Composer 不 fallback，也不提示替代分支

语义化版本不是靠“越锁越死”来获得安全感，而是靠理解 ^ 和 ~ 的边界、看清 dev- 的真实行为、以及始终让 composer.json、composer.lock、执行命令三者对齐。最危险的不是版本升级，是你以为锁住了，其实没锁住。