Composer self-update 默认只升级同主版本内的小版本，不跨主版本；需用 --stable、--preview 或指定版本号强制升级。

Composer 的 self-update 命令能升级自身，但默认只升到当前稳定分支的最新小版本（比如 2.5.x → 2.5.y），不会跨主版本（如 2.x → 3.x）。

为什么 composer self-update 没有升级到最新版？

Composer 默认启用“稳定通道”（stable channel），且自 2.2 起默认禁用自动跨主版本升级。即使运行 composer self-update，它也只会检查并安装同主版本下最新的补丁/次版本，比如从 2.5.8 升到 2.5.12，但不会升到 2.6.0 或 3.0.0。

• 检查当前版本：composer --version
• 查看可用更新策略：composer self-update --help
• 若看到 Up to date 但你知道有新主版本，说明它被策略拦截了

如何强制升级到指定主版本（如 2.x 最新版或 3.x）？

必须显式指定版本号或通道。Composer 提供 --stable、--preview、--snapshot 等通道，也可直接指定版本字符串。

• 升到当前稳定主版本的最新版（推荐日常使用）：composer self-update --stable
• 升到预发布版（含 RC/Beta）：composer self-update --preview
• 升到特定版本（如强制切到 2.7.7）：composer self-update 2.7.7
• 升到 v3 预览版（实验性，不建议生产环境）：composer self-update --preview --1 或 composer self-update --preview --2 已废弃，v3 需用 --3（如果已支持）；目前（2025 年中）Composer v3 尚未正式发布，--3 会报错，应避免

升级失败常见原因和绕过方式

权限、网络、二进制锁定都可能导致 self-update 失败，错误信息常为 Could not write to /usr/local/bin/composer 或 file_put_contents(…): failed to open stream。

• 权限不足：Linux/macOS 下，若 Composer 安装在系统路径（如 /usr/local/bin），需加 sudo：sudo composer self-update
• Windows 上以管理员身份运行命令提示符或 PowerShell
• 某些环境（如 Docker、CI）中 Composer 是只读二进制，此时 self-update 必然失败 —— 应改用重新下载安装：

  php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
  php composer-setup.php --filename=composer --install-dir=/usr/local/bin
  php -r "unlink('composer-setup.php');"

• 国内用户可能因网络问题卡住：可临时设置镜像源（仅对下载有效）：export COMPOSER_HOME=~/.composer && composer self-update -vvv，再配合 curl -L https://mirrors.aliyun.com/composer/ 手动下载替换

真正要注意的是：升级后 composer.json 中的 require 规则、插件兼容性和 lock 文件生成逻辑可能变化，尤其是跨大版本时。别只盯着 self-update 成功与否，升级后务必跑一次 composer install 并检查依赖解析是否符合预期。

# php  # linux  # js  # json  # docker  # composer  # windows  # mac  # curl  # ai  # macos  # date  # require