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><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill11153" title="智能 Git 操作助手"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20d3191a227.jpg" alt="智能 Git 操作助手" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill11153" title="智能 Git 操作助手" class="overflowclass">智能 Git 操作助手</a>
<p class="overflowclass">>-智能 Git 操作助手：安全提交、合并分支、检测冲突并提供处理建议、生成可视化报告。</p>
</div>
<a rel="nofollow" href="/xiazai/skill11153" title="智能 Git 操作助手" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div><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 解析。
