Composer install 总是重拉私有 Git 仓库，是因为 VCS 缓存（{$cache-dir}/vcs）需 URL 完全一致、仓库未变更、cache-dir 可写且权限正确才生效；常见失效原因包括动态 token、协议混用、缓存目录被清理或挂载只读、HTTPS 重定向未复用缓存等。
Composer 无法自动复用 Git 仓库的 VCS 缓存，除非你手动配置好 cache-dir 和 vcs 目录权限，并确保每次 clone 使用相同 URL 形式（含 token 或 SSH）。
为什么 composer install 总是重拉私有 Git 仓库？
Composer 的 VCS 缓存（{$cache-dir}/vcs）只在以下条件同时满足时才生效：URL 完全一致（包括协议、host、path、query 参数）、Git 仓库未被修改（如新 tag 推送后需更新缓存）、且 cache-dir 可写。常见失效原因：
- HTTPS URL 中 token 每次生成不同（如用
date +%s动态拼接），导致缓存 key 不匹配 - 混用
https://和git@gitlab.example.com:两种协议，Composer 视为两个独立仓库 -
~/.composer/cache/vcs/目录被 CI 清理脚本误删，或挂载卷权限错误（如 root 写、www-data 读） - 私有 Git 服务启用了强制 HTTPS 重定向，但 Composer 请求返回 302 后未复用缓存（旧版存在此问题，建议升级至 Composer 2.5+）
cache-dir 和 vcs 子目录必须显式可写
Composer 默认把 VCS 缓存放在 {$cache-dir}/vcs，但它不会自动创建父目录或修复权限。若你在 Docker 或 CI 中自定义 cache-dir，必须确保：
- 路径存在且由运行 composer 的用户（如
www-data或runner）拥有 - 执行
composer config --global cache-dir /tmp/composer-cache后，立刻运行mkdir -p /tmp/composer-cache/vcs && chown runner:runner /tmp/composer-cache/vcs - 避免将
vcs目录挂载为只读（GitHub Actions 的actions/cache默认只恢复files和repo，不包含vcs）
私有 Git 服务 URL 必须稳定，不能带动态参数
VCS 缓存 key 基于完整 URL 哈希生成，任何 query string 变更都会导致缓存 miss。例如：
# ❌ 动态 token 导致每次 URL 不同，缓存失效
"https://oauth2:abc123@gitlab.example.com/myorg/pkg.git"
"https://oauth2:def456@gitlab.example.com/myorg/pkg.git"
<h1>✅ 固定 token + 环境变量注入（推荐 CI 场景）</h1><p>COMPOSER_AUTH='{"gitlab.example.com":{"token":"abc123"}}'</p><h1>URL 写成 "<a href="https://www.php.cn/link/9fbd07081692403c9ce48c1d55d8c8fc">https://gitlab.example.com/myorg/pkg.git"，无需嵌入</a> token</h1>使用 COMPOSER_AUTH 环境变量比硬编码 token 更安全，也更利于缓存复用。注意：gitlab-oauth. 配置项仅对 GitLab 有效，GitHub 对应的是 github-oauth.github.com。
CI 中启用 VCS 缓存需额外声明 vcs 路径
GitHub Actions 的 actions/cache 默认不缓存 vcs 目录，但你可以显式添加：
- name: Cache Composer vcs cache
uses: actions/cache@v4
with:
path: ~/.composer/cache/vcs
key: ${{ runner.os }}-composer-vcs-${{ hashFiles('**/composer.lock') }}
不过要注意：VCS 缓存体积大（单个 Git 仓库可达百 MB），且只在多次 composer update 或切换分支时收益明显；日常 composer install 主要靠 files 缓存提速。真正容易被忽略的是——vcs 缓存不会加速首次 clone，它只加速后续 fetch/pull/tag 解析。
