“file could not be downloaded”错误在国内几乎从不表示真断网，而是Composer仍在直连packagist.org或缓存复用失败响应；必须同步切阿里云镜像（composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/）并清缓存（composer clear-cache）。
“file could not be downloaded”不是断网，是镜像没生效或缓存卡住
这个报错在国内几乎从不表示真断网，而是 Composer 仍在尝试直连 packagist.org，或者本地缓存里存着上次失败的响应体，重试时直接复用——它根本没发新请求。
必须同步做两件事：
- 切阿里云镜像：
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ - 清缓存：
composer clear-cache（只清缓存不删 vendor）
如果 composer config -g repos.packagist 输出为空或报错，说明全局配置根本没写进去；如果项目根目录有 composer.json 且含 "repositories" 字段（哪怕值是空数组），就会覆盖全局镜像，此时要查 composer config repo.packagist（不加 -g）。
“Loading composer repositories” 卡死，大概率是 SSL 或代理问题
卡在这一步，-vvv 日志里通常会出现 cURL error 60、unable to get local issuer certificate 或静默超时。这不是 Composer 配置问题，而是 PHP 的 cURL 根证书路径没设对。
操作步骤：
- 运行
php --ini找到真实加载的php.ini路径 - 编辑该文件，取消注释并修正
curl.cainfo，例如：curl.cainfo = "C:\php\cacert.pem"（Windows）或curl.cainfo = "/etc/ssl/certs/ca-certificates.crt"（Linux） - 企业内网若走 HTTP 代理，补上：
composer config -g http-proxy http://10.0.1.100:8080 - 临时绕过 TLS 校验（仅限开发机）：
composer config -g secure-http false
离线环境装包？别信“先下载再 install”，得靠 packages.json 元数据
纯离线环境（比如生产服务器完全无外网）下，composer install 能跑通的前提不是 vendor 目录存在，而是 composer.lock + 完整的私有仓库元数据（packages.json 及每个包的 dist URL 和 require 字段）都已就位。
常见漏点：
- 私有仓库（如 Satis）生成时没开
"require-dependencies": true，导致packages.json里缺失require字段，Composer 就当包没有子依赖 - 用
type: "package"手动声明本地 ZIP 包，但没在dist下写全"url"和"shasum"，或shasum和实际 ZIP 不一致 -
composer.lock中的distURL 指向的是packagist.org域名，离线时无法解析——必须提前用私有源重生成 lock 文件
为什么 composer install --ignore-platform-reqs 装完还报错
这个参数只跳过 PHP 版本和扩展校验，不解决底层兼容性。比如你用 PHP 8.0 装了要求 ext-opcache 的包，--ignore-platform-reqs 让 install 成功，但运行时仍会抛 Class 'Opcache' not found。
真正该做的：
- 先运行
composer check-platform-reqs，它会明确列出缺哪些扩展、PHP 版本差多少 - 确认
php -m | grep opcache（或对应扩展名）是否真加载 - 检查 CLI 和 Web 使用的
php.ini是否为同一份：php --inivsphpinfo()页面里的 Loaded Configuration File - 别在 CI 脚本或生产部署中用
--ignore-platform-reqs，它掩盖的是环境一致性漏洞
离线或弱网环境下，最易被忽略的是元数据完整性——composer.lock 不是快照，它依赖外部仓库的 packages.json 结构；而 packages.json 若没导出 require 字段，Composer 就永远不知道子依赖在哪。
