composer 依赖 php ≥ 7.4，macos 12+ 需用 homebrew 安装 php 并配置 path；官方弃用 brew install composer，应通过 curl 安装并移至 /opt/homebrew/bin/composer；务必配置阿里云镜像源防超时。
PHP 没装或版本太旧，composer 一定跑不起来
Composer 是 PHP 写的命令行工具，不是独立程序。macOS 自带的 PHP 早在 macOS 12+ 就被苹果移除了，直接运行 php -v 报 command not found: php 是常态；就算有，也大概率是过时的 PHP 7.3 或更低版本，而 Composer 2.x 要求 PHP ≥ 7.4（推荐 8.1+）。
- 先确认：运行
php -v，看是否输出有效版本（如PHP 8.3.12） - 没装或版本低：用 Homebrew 安装最新稳定版 PHP：
brew install php - M1/M2 Mac 用户注意：
which php应返回/opt/homebrew/bin/php；如果返回空或/usr/bin/php，说明没走 Homebrew 的 PHP，需检查~/.zshrc是否含export PATH="/opt/homebrew/bin:$PATH"并执行source ~/.zshrc
别用 brew install composer，它已被弃用且在 M1/M2 上常出问题
Homebrew 官方自 2023 年起已将 composer 包标记为 deprecated。这不是“不推荐”，而是明确停止维护——你会遇到版本陈旧（卡在 2.5.x）、路径错乱（比如装到 /opt/homebrew/Cellar/... 却没软链）、甚至权限失败（Permission denied）等真实报错。
- 官方唯一推荐方式是 curl 安装脚本：
curl -sS https://getcomposer.org/installer | php（生成composer.phar） - 移动到全局可执行位置（M1/M2）：
sudo mv composer.phar /opt/homebrew/bin/composer - 赋权（否则执行时报
Permission denied）：sudo chmod +x /opt/homebrew/bin/composer - 验证：
composer --version应输出类似Composer version 2.7.7
which composer 返回空或错误路径，说明环境变量没生效
MacOS 12+ 默认 shell 是 zsh，它只读 ~/.zshrc（不是 ~/.bash_profile）。很多人改了配置却没生效，本质是写错文件、没 reload、或 PATH 顺序不对。
- 运行
echo $SHELL确认是/bin/zsh，那就只动~/.zshrc - 确保
/opt/homebrew/bin（M1/M2）或/usr/local/bin（Intel）已在 PATH 开头：export PATH="/opt/homebrew/bin:$PATH" - 改完必须执行：
source ~/.zshrc；新开终端不会自动加载旧配置 - 验证是否真全局可用：换到任意目录（如
cd ~/Desktop），再运行composer --version；同时查路径：which composer必须返回/opt/homebrew/bin/composer或/usr/local/bin/composer
不配国内镜像源，composer install 很可能卡死或超时
默认源 https://repo.packagist.org 在国内访问极不稳定，尤其从 2025 年底起，超时（Connection timed out）和 SSL 握手失败越来越常见。这不是网络问题，是源站路由问题。
- 配阿里云镜像（最稳）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 验证是否生效：
composer config -g repo.packagist应输出镜像 URL - 如果项目里已有
composer.json且之前失败过，先删掉vendor/和composer.lock再重试
最容易被忽略的点是：改完 ~/.zshrc 没 source，或者 which composer 显示的是当前目录下的 ./composer —— 那根本不是全局安装，只是临时能跑而已。装完一定要跨目录验证，不然后面所有 composer require 都会莫名其妙失败。
