本地镜像调试前必须确认三件事：一、composer命令可用且版本≥2.9.6；二、PHP已启用curl和openssl扩展；三、终端用户与Composer实际执行用户一致。
本地镜像调试前必须确认的三件事
Composer 本地镜像调试不是“换源就行”，而是要先排除基础干扰。很多看似镜像失效的问题，其实根本没走到镜像请求那步。
-
composer命令本身是否可用？运行composer --version确认输出的是Composer 2.9.6或更高版本（低版本对repo.packagistkey 支持不一致） - PHP 是否启用了
curl和openssl扩展？缺任一者都会导致连接失败，且错误信息常被误读为“镜像不可用” - 当前终端用户与实际执行 Composer 的用户是否一致？比如在宝塔或 code-server 中，
-g配置写入的是root的~/.composer/config.json，但后台任务可能以www用户运行——此时需切换到该用户再配一次
用 --repository 参数绕过所有配置做原子验证
这是最快定位问题根源的方式：它完全忽略全局、项目级、环境变量等所有持久化设置，只走你当次指定的 URL。适合验证某个镜像地址是否真能响应，以及排除 JSON 格式、字段名拼写等配置污染。
- 正确写法：
composer install --repository=https://mirrors.aliyun.com/composer/ - 错误写法：
--repository-url、--mirror、--source—— Composer 不识别，会静默回退到默认源 - 加
-vvv查看真实请求：composer install -vvv --repository=https://mirrors.aliyun.com/composer/，输出中应出现https://mirrors.aliyun.com/composer/packages.json这类路径，而非packagist.org - 若仍报 404，请检查 URL 末尾是否有斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌
项目级配置如何避免破坏私有包源
很多 PHP 扩展项目依赖私有仓库（如 GitHub Enterprise、GitLab 私有组），一旦手动编辑 composer.json 的 repositories 字段，极易因 JSON 格式错误或覆盖原有配置导致私有包拉取失败。
- 安全做法：进项目根目录后，直接运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不带-g） - 这条命令会自动检测已有
repositories数组，并在首位插入 packagist 镜像对象，不会删掉你已有的私有源 - 若手动编辑，必须保证结构合法：
"repositories": [{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}, {"type":"git","url":"https://git.example.com/private.git"}] - 切勿添加
"packagist": false—— 这会禁用全部 packagist 包，包括ext-redis、ext-mbstring等扩展依赖的元数据
调试时最容易被忽略的缓存陷阱
Composer 缓存机制会让错误配置“看起来生效”，实则仍在用旧数据。尤其在反复切换镜像源时，vendor/ 和 composer.lock 是最常被遗忘的清理点。
立即学习“PHP免费学习笔记（深入）”；
- 每次更换镜像后首次运行
composer install，若报hash does not match或could not find package，不要硬扛，立刻执行：rm -rf vendor/ composer.lock（Windows 用rmdir /s vendor && del composer.lock） - 清除 Composer 自身缓存：
composer clear-cache，否则它可能从本地缓存返回过期的packages.json - 注意：某些 CI 环境（如 GitHub Actions）默认启用缓存，需在 workflow 中显式禁用或刷新
~/.composer/cache
真正卡住调试进度的，往往不是镜像地址本身，而是缓存残留、用户权限错位、或 JSON 手动编辑时一个漏掉的逗号。验证时优先用 --repository 跑通单次请求，再回退到项目级配置固化，比反复修改全局配置更可控。
