Composer离线可用的缓存仅限files/子目录下的zip包；必须通过composer config --global cache-files-dir指定该路径，并配合--prefer-dist下载，否则其他缓存（如repo/）断网即失效。
composer 本地缓存不是“建立”出来的，而是你每次运行 composer install 或 composer update 时自动写入的产物；真正能复用、迁移、离线用的，只有 files/ 子目录下的 zip 包 —— 其他缓存路径（比如 repo/）在断网时基本失效。
为什么改了 cache-dir 还是没缓存？
常见错觉：以为只要设了 cache-dir 就万事大吉。实际它只是个混合目录，里面混着 repo/（元数据）、archived/（解压后归档）、files/（原始 dist zip）——但只有 files/ 下的 vendor/package/version.zip 才能在离线时被 --prefer-dist 直接读取。
-
cache-dir被设成/dev/null或只读路径 → 缓存写不进去 - 项目里写了
"config": { "cache-dir": false }→ 直接禁用缓存 - CI 脚本里漏了
--no-cache的反向操作，或根本没挂载持久卷 → 每次构建都是空缓存 - PHP 进程用户（如
www-data）对~/.composer/cache无写权限 → 日志里静默失败
cache-files-dir 是离线场景唯一该配的路径
这个配置项专为离线设计，只控制 files/ 子目录位置，不干扰 repo/ 或 archived/。一旦设好，composer install --prefer-dist 就会把所有下载的 zip 包强制写进该路径，方便打包带走。
- 先清旧配置：
composer config --global --unset cache-dir（避免和cache-files-dir冲突） - 设新路径：
composer config --global cache-files-dir /path/to/offline-cache - 触发下载：
composer install --no-autoloader --no-scripts --prefer-dist - 验证是否生效：检查目标路径下是否有类似
monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip的结构
备用本地镜像源怎么配才不静默失效？
镜像源配置错一个字符，就会静默 fallback 到 packagist.org，且 composer diagnose 还显示 “Repo packagist.org is default”。关键不是 URL 对不对，而是三要素缺一不可：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 键名必须是
repo.packagist（单数，不能是repos.packagist或packagist.org） -
type值必须显式写composer（不是可选参数，也不是注释） - URL 必须 HTTPS 开头 + 末尾带
/（例如https://mirrors.aliyun.com/composer/✅，少斜杠就 404）
验证命令：composer config -g repo.packagist，输出必须是完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、报错、或只返回字符串，都说明没生效。
换源后为什么 composer search 还慢？
search 默认强制刷新元数据：先 GET https://repo.packagist.org/packages.json，再逐个请求上百个 provider-xxx.json 分片索引。没镜像时，95% 时间耗在 DNS + TLS 握手上。
- 必须执行
composer clear-cache（别手动删~/.composer/cache，容易权限错乱） -
--repository参数对search不生效（Composer ≥2.2 已明确限制） - 即使开了
parallel-downloads，也只加速 tarball 下载，对search完全无效 - 首次
composer search laravel仍稍慢（重建缓存），之后才是秒级响应
composer config -g repo.packagist 输出为空、files/ 目录始终空着、search 还在等 10 秒——这些信号都在告诉你：缓存链路某处断了，而且 Composer 绝不会主动告诉你断在哪。 
