缓存读取失败时 Composer 常报 file could not be downloaded、JSON_ERROR_SYNTAX 或卡在 Writing lock file，主因是缓存中 JSON/zip 文件损坏或权限归属错误（非 chmod 问题），需手动排查 composer.json、auth.json 及缓存目录 packages.json，并彻底清理缓存。
缓存读取失败时 Composer 会报什么错误
常见错误不是“缓存不存在”，而是更隐蔽的链式失败：比如 file could not be downloaded、Failed to decode response: JSON_ERROR_SYNTAX、甚至直接卡在 Writing lock file 不动。这些大多不是网络问题，而是 Composer 尝试从缓存里读一个已损坏的 JSON 或 zip 文件，解析失败后没抛明确提示，反而退回到下载逻辑——结果你反复重试，实际一直在读坏缓存。
先确认是不是缓存目录本身不可读写
Composer 读缓存前得先打开目录、遍历子路径、解压文件。如果缓存根目录权限不对，它连第一步都过不去：
- 运行
composer config --global cache-dir拿到路径，再ls -ld看归属和权限；若 owner 是root，执行sudo chown -R $USER:$USER $(composer config --global cache-dir) - Windows WSL 用户特别注意：
/mnt/c/下的路径不支持 Linux 权限模型，chown无效，必须把缓存切到~/composer-cache这类原生 Linux 路径 - 别信
chmod -R 777—— 它改的是权限位，但 Composer 卡住的主因是归属错，不是rwx不够
缓存里哪个文件坏了？按优先级手动排查
Composer 会依次读取三类缓存 JSON：项目级 composer.json → 全局 ~/.composer/auth.json → 缓存目录下的 packages.json（含解压后的临时 JSON）。顺序不能乱：
- 先跑
composer validate，只校验当前composer.json；失败就用php -r "json_decode(file_get_contents('composer.json')); echo json_last_error_msg();"定位行号 - 若 validate 通过，但
install仍报 JSON 解析错，检查~/.composer/auth.json—— 尤其你手动粘过 OAuth token，容易多逗号或换行符 - 最后清缓存：但
composer clear-cache不一定删干净，因为缓存中 .json.gz 解压后的临时文件可能残留；更彻底的做法是rm -rf $(composer config --global cache-dir)（Windows 用rd /s/q "%APPDATA%\Composer\Cache"）
换源后还读旧缓存？配置覆盖和缓存快照要分开处理
换镜像源后 install 依然慢或失败，大概率是两件事没做清：
-
composer config repo.packagist输出不是你设的镜像地址？说明被项目级repositories块覆盖了，要么删掉该字段，要么显式执行composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 即使配置生效，缓存里仍存着旧镜像返回的
packages.json快照（二进制格式），clear-cache才能刷新；否则 Composer 会继续拿这个旧快照去查包，自然找不到新源上的更新 - 私有 Packagist 用户注意：如果服务端返回的 JSON 本身就有语法错误（比如漏括号、BOM 头），Composer 一样会报
Unexpected end of JSON—— 此时 curl 直接请求 API 看响应体比修本地更有效
缓存读取失败最麻烦的地方在于：它不报“缓存损坏”，只报下游错误。盯住 composer install -v 输出里第一行 “Reading packages.json from cache” 后是否立刻跳到下载，就能判断缓存是否被跳过或解析失败。
