composer国内用户需配置镜像源并清除缓存：先确认php环境（php -v）、正确安装composer.phar为全局命令、立即设置阿里云或中科大镜像（composer config -g repo.packagist https://mirrors.aliyun.com/composer/），再执行composer clear-cache。
composer 安装后默认走国外源，国内用户不配镜像基本没法用——下载卡死、超时、反复重试是常态，不是你网络差，是源本身不可达。
确认 PHP 环境是否就绪
composer 本质是 PHP 脚本，必须依赖可用的 php 命令。很多新手卡在这一步却以为是 composer 问题：
- 运行 php -v，必须有输出（PHP 7.4+ 推荐）
- 若提示 command not found: php，说明 PHP 未安装或未加入 PATH
- Windows 用户常见问题是安装了 PHP 但没勾选“Add to PATH”，或路径含空格/中文
- Linux/macOS 用户若用宝塔，确保在终端里用的是宝塔管理的 PHP（如 /www/server/php/82/bin/php），而不是系统自带的老版本
安装 composer.phar 并设为全局命令
不要双击安装器完事，要能从任意目录执行composer：
- Linux/macOS：
curl -sS https://getcomposer.org/installer | phpsudo mv composer.phar /usr/local/bin/composersudo chmod +x /usr/local/bin/composer
- Windows：
下载 Composer-Setup.exe 时务必勾选 “Add to PATH”
若漏了，手动把 C:\ProgramData\ComposerSetup\bin 加进系统环境变量
- 验证：直接运行 composer --version，有输出即成功
- 坑点：某些云服务器预装的 PHP 缺少 openssl 或 zlib 扩展，composer 会报错“file_get_contents(): SSL operation failed”，需进 php.ini 开启对应扩展
立刻配置国内镜像，否则寸步难行
不改镜像，composer install 很可能卡在 “Loading composer repositories with package information” 十几分钟不动：
- 全局生效（推荐，一劳永逸）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
或中科大源：composer config -g repo.packagist composer https://mirrors.ustc.edu.cn/composer/
- 验证是否写入：composer config -g repo.packagist，应返回镜像 URL
- 注意：宝塔面板用户，/root/.composer/config.json 是 root 用户的全局配置，普通网站用户可能读不到；若用宝塔创建的站点用户执行 composer，得用该用户身份再跑一遍 config -g，或改用项目级配置
- 临时覆盖（调试用）：composer install --repository-url=https://mirrors.huaweicloud.com/repository/php/初始化项目前先检查权限和路径
composer init 或 composer require 报错 Permission denied / Cannot create cache directory，往往不是镜像问题：
- Linux 下确保当前用户对项目目录有读写权限，尤其宝塔中用 www 用户运行的站点，别用 root 直接在根目录操作
- ~/.composer/cache（Linux/macOS）或 C:\Users\XXX\AppData\Roaming\Composer\Cache（Windows）若被锁死或磁盘满，也会导致命令卡住
- 宝塔文件管理器里右键“设置权限”，勾选“递归设置子目录文件权限”，755/644 即可，别盲目 777
- 如果之前用过已失效的镜像（如 packagist.phpcomposer.com），它已被弃用，强行使用会返回 404，删掉旧配置再重试
镜像不是万能的，但没镜像是真不行。最常被忽略的一点：配置完镜像后，composer clear-cache 必须执行一次——否则旧缓存里的错误响应可能持续干扰后续操作。
