Composer outdated –direct 仅查看直接依赖的过期包【筛选】

composer outdated –direct 只显示当前已安装且有更新可用的直接依赖，不列出已是最新版或版本锁定无更新的包；它默认忽略 require-dev，需加 –dev 参数；受版本约束、php 版本等限制，实际升级仍需 –dry-run 验证。

composer outdated –direct 为什么只显示部分直接依赖

composer outdated --direct 并非列出所有 require 中声明的包，而是只显示「当前已安装且有更新可用」的直接依赖。如果某个直接依赖已是最新稳定版（或满足 composer.json 中的版本约束），它根本不会出现在输出里——不是漏了，是没得可报。

常见误解是以为它像 npm outdated --depth=0 那样强制罗列全部直接依赖并标出是否过期。Composer 没这个逻辑，它只做“有更新才说话”。

• 若某包被锁在 composer.lock 中的旧版本，但 composer.json 允许更高版本（如 "monolog/monolog": "^2.0"），且新版本存在，则会显示
• 若 composer.json 写死版本（如 "guzzlehttp/guzzle": "7.4.5"），而该版本仍是官方最新发布版，就不会出现
• 若包已弃用（abandoned），且无替代包，--direct 也不会特别标注，需人工核对

如何让 –direct 显示更全的“潜在可升级项”

想看到所有直接依赖（无论是否真有更新），就得绕过 outdated 的默认过滤逻辑。最实用的办法是结合 show 和本地比对：

运行 composer show --direct --no-dev 获取当前所有直接依赖及其已安装版本，再手动或脚本比对 packagist 上的最新稳定版。没有内置命令能一步到位，但可快速写个简短 shell 命令辅助：

composer show --direct --no-dev | awk '{print $1}' | xargs -I{} sh -c 'echo "{}: $(curl -s "https://packagist.org/packages/{}.json" | jq -r ".package.versions[0].version // "n/a"")"'

注意：这依赖 jq，且受 Packagist API 限流影响，仅适合临时排查。生产环境建议用 composer outdated --direct --minor-only 或 --patch-only 缩小范围，避免误升大版本。

–direct 不检查 require-dev 的原因和应对

composer outdated --direct 默认忽略 require-dev，这是设计使然：它只作用于 require 区块中声明的运行时依赖。开发依赖需显式加 --dev 参数：

• composer outdated --direct --dev：只看 require-dev 中有更新的包
• composer outdated --direct --with-dependencies：仍不包含 dev 包，该参数只影响依赖树展开层级
• 若想同时检查两者，目前只能分两次运行，或用 composer outdated --all（但会混入大量间接依赖，噪音大）

很多 CI 流程会漏掉 --dev，结果上线前才发现 phpunit 或 phpstan 已严重滞后——这不是 bug，是默认行为。

容易被忽略的版本约束干扰项

即使 --direct 列出了某个包，也不代表 composer update vendor/package 一定能升到最新版。以下情况会导致升级失败或降级：

• 其他直接依赖对该包有冲突的版本约束（例如 A 要求 ^2.0，B 要求 ^1.8）
• PHP 版本不匹配：新版本可能要求 PHP 8.1+，而当前环境是 8.0
• composer.json 中启用了 "minimum-stability": "beta"，但你想升的是 stable 版，Composer 可能跳过
• 包作者在 Packagist 上标记了 replaced 或 replaces，导致解析路径异常

真正要确认能否安全升级，不能只信 outdated 输出，得跑一次 composer update vendor/package --dry-run 看解析结果。否则很容易在部署时卡住。