答案是网络连不通、权限不对或路径挂错分区导致，需先用ping和curl验证DNS与连接链路，再正确配置镜像源（键名repo.packagist、type值composer、URL末尾带/）、清缓存，排查sudo污染、/Volumes/挂载问题及PATH配置。
绝大多数 composer install 失败，不是 Composer 有问题，而是网络连不通、权限不对、或路径挂错了分区。
报 “Could not resolve host” 或 “Connection refused” 怎么办
这不是 Composer 卡了，是系统根本没连上镜像源。先别急着改 composer.json，看 DNS 和连接链路：
- 运行
ping packagist.org：如果返回unknown host，说明 DNS 解析失败，立刻换 DNS（比如8.8.8.8） - 运行
curl -v https://mirrors.aliyun.com/composer/：卡在* Connected to是网络层问题；卡在* TLS handshake是证书或 IPv6 兼容性问题，加环境变量CURL_IPRESOLVE=4强制走 IPv4 -
composer config -g repo.packagist输出必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}—— 少斜杠、少type、键名写成repos.packagist都会静默失效 - 换源后必须执行
composer clear-cache，否则旧缓存还在，重试照样走原地址
报 “Permission denied” 写 vendor 或 composer.lock
90% 是目录被 sudo 污染过，属主变成 root，而你现在用普通用户跑命令。别直接 chmod 777，先查归属：
- 运行
ls -ld vendor/ composer.lock：如果显示root在 owner 列，就说明问题在这 - 修复命令：
sudo chown -R $USER:$USER /path/to/your/project（注意替换真实路径） - 特别注意
~/.composer目录也要归你：ls -ld ~/.composer，不对就sudo chown -R $USER:$USER ~/.composer - 永远不要用
sudo composer install—— 它生成的文件你后续根本改不了
在 /Volumes/ 下运行 install 直接失败
外接硬盘、虚拟机共享目录、Parallels 拖进来的项目，只要路径含 /Volumes/，composer install 几乎必挂。这不是 Composer bug，是文件系统不支持：
- 验证方式：在项目根目录运行
touch test-perm && rm test-perm，失败就确认是挂载问题 - NTFS/fuse 挂载点不支持 Unix 权限和大小写敏感，
vendor/根本建不出来，chmod和chown全无效 - 临时解法：把项目复制到本地 APFS 分区，比如
~/Sites/myapp或~/Code/myapp，再跑composer install - 别试图改
COMPOSER_VENDOR_DIR到同挂载点下——一样失败
装完命令找不到，或只在安装目录能跑
composer 不是没装，是 shell 找不到它。M1/M2 Mac 尤其容易漏掉 Homebrew 路径：
- 先确认 PHP 可用：
which php必须输出/opt/homebrew/bin/php（M 系列）或/usr/local/bin/php（Intel），否则 Composer 跑不起来 - Composer 本体路径要加进
PATH：export PATH="/opt/homebrew/bin:$PATH"（M 系列）或export PATH="/usr/local/bin:$PATH"（Intel）——写在~/.zshrc末尾，然后source ~/.zshrc -
$COMPOSER_HOME/vendor/bin必须单独加进PATH：export PATH="$HOME/.composer/vendor/bin:$PATH"，否则laravel、phpunit这类全局命令还是找不到 - 验证是否生效：
which composer应输出绝对路径，cd ~/Sites/myapp && composer --version必须成功
最常被忽略的是：项目级 repositories 配置会让全局镜像完全失效；/Volumes/ 路径下连 touch 都失败时，强行改权限毫无意义；COMPOSER_HOME 不能写 ~/.composer，必须是绝对路径。
