composer update --root-reqs 仅更新 composer.json 顶层声明的依赖，不主动升级子依赖，但仍会重新解析全图以确保约束满足，可能间接影响子依赖版本；适用于精准升级直接依赖、CI 验证或锁文件过时时的小步迭代。
composer update --root-reqs 确实只更新 composer.json 顶层声明的依赖，不触碰锁文件里已解析的子依赖树——但它不是“安全更新”的代名词，用错场景反而会破坏依赖一致性。
什么时候该用 --root-reqs
适用于明确只想升级某几个直接依赖（比如把 laravel/framework 升到 11.x），又不想让 Composer 顺手把 symfony/console、monolog/monolog 这类间接依赖也按最新兼容版本拉取的情况。
- 你手动改了
composer.json里某个包的版本约束（如"phpunit/phpunit": "^10.5"），只想让它生效，不希望其他包连带变动 - CI 流程中需复现某次特定根依赖升级的影响，排除子依赖浮动干扰
- 项目锁文件已严重过时，但你暂时不敢跑全量
update，先小步验证关键依赖
--root-reqs 不等于“跳过子依赖解析”
它仍会重新解析整个依赖图来确认新版本是否满足所有约束，只是最终只写入那些在根 composer.json 中显式列出的包及其新版本号到 composer.lock。子依赖的版本可能被间接影响——比如你升级 guzzlehttp/guzzle 到 8.x，它要求 psr/http-client >= 1.0，那么即使你没在根里声明后者，它的最小版本也可能被提升。
- 执行后务必检查
composer.lock变更：搜索被修改的包名，再顺藤摸瓜看其requires项是否引发连锁变动 - 若想彻底冻结子依赖，得配合
--with-dependencies或干脆不用此选项，改用require --update-with-dependencies显式控制 -
--dry-run在这里很有用：先跑一遍看看实际会动哪些包，比盲升更可靠
常见误用与报错
最典型的是执行后发现某些包没更新，或提示 Root package ... is not required in your composer.json。
- 传入的包名拼写错误或不在根
composer.json的require/require-dev字段里——--root-reqs不接受任意包名，只认顶层声明项 - 用了
composer update vendor/package --root-reqs：这个命令格式无效；正确写法是composer update --root-reqs（无参数），或composer update vendor/package（无--root-reqs） - 锁文件损坏或本地 vendor 不完整时，
--root-reqs可能静默失败，建议先composer install确保环境干净
真正要稳住依赖树，靠的不是跳过解析，而是理解 composer.lock 的作用边界——--root-reqs 是个精准手术刀，但切哪一刀，得先看清血管走向。
