根本原因是Docker构建环境隔离导致Composer的VCS缓存（~/.composer/cache/vcs/）为空，每次需重新git clone私有仓库；解决方法是在builder阶段执行composer install填充缓存，并COPY至最终镜像，同时确保UID一致、lock文件更新以匹配Git commit hash。
为什么 Docker 里 composer install 还要重新 clone Git 仓库？
不是网络慢，是 Composer 的 VCS 缓存（~/.composer/cache/vcs/）在容器启动时为空——每次构建都从头 git clone，尤其对私有 GitLab/GitHub 仓库，还会触发 token 验证、SSH key 加载、2FA 检查等额外开销。
根本问题在于：Docker 构建是隔离环境，宿主机的 Composer 缓存进不去容器；而默认镜像（如 php:8.3 或 composer:2）根本不带任何 VCS 缓存数据。
- 运行
composer install -vvv时看到Cloning into '/tmp/...'或Executing command (CWD): git clone --no-checkout ...，说明正在实时克隆 -
composer diag输出中VCS cache directory指向容器内路径（如/root/.composer/cache/vcs），且该目录为空或只含极少量元数据 - 即使你用了
--prefer-dist，只要包定义为"type": "vcs"（比如私有 Git 仓库），Composer 仍会 fallback 到源码模式并尝试 clone
如何把 VCS 缓存“ baked in ”到 Docker 镜像里？
不能靠 composer clear-cache 或 composer update --no-cache 解决——这些命令只影响运行时，不固化缓存。必须在构建阶段主动填充 vcs/ 目录，并确保后续构建能复用。
- 在构建阶段（例如多阶段中的 builder 阶段）执行一次完整
composer install，让 Composer 自动填充~/.composer/cache/vcs/ - 显式复制该缓存目录到最终镜像：用
COPY --from=builder /root/.composer/cache/vcs /root/.composer/cache/vcs - 确保 builder 阶段使用与运行时一致的用户 UID，否则权限错位会导致缓存不可读（如 builder 用 root，runtime 用
www-data，就得chown -R www-data:www-data /root/.composer/cache/vcs） - 若项目含多个私有 VCS 包，首次构建后可手动验证缓存是否命中：
ls -l /root/.composer/cache/vcs/应看到按域名/路径组织的子目录，如gitlab.example.com$myorg$my-package.git/
path 仓库在 Docker 里为何完全失效？
"type": "path" 是开发模式快捷方式，依赖宿主机文件系统挂载，**Docker 构建过程无法访问 host 路径**。一旦进入 docker build，所有 ../my-package 引用都会被忽略或报错 Source path ../my-package does not exist。
- CI/CD 流水线或生产镜像中必须禁用
repositories中的path条目，改用vcs或package类型 - 若坚持本地联调，应在
docker run时用-v挂载本地包目录，并在容器内手动rm -rf vendor/vendor/name+composer update vendor/name --no-cache - 更稳妥的做法：开发期用
path，CI 构建前用脚本自动注释掉repositories中的path条目，并启用vcs备份源
缓存内容变了，怎么让 Docker 构建感知并更新？
VCS 缓存本身不会自动感知 Git 仓库的 commit 变更。Composer 是否拉新代码，取决于 composer.lock 中记录的 commit hash —— 它才是事实来源，不是缓存目录里的快照。
- 修改私有包代码后，必须在包根目录运行
git add . && git commit -m "update"，再回到主项目执行composer update vendor/name --with-dependencies更新 lock 文件 - Docker 构建时，只要
composer.lock文件变动，就会触发依赖重装，此时 Composer 会检查 VCS 缓存中是否有匹配 hash 的 clone，有则复用，无则重新 clone - 不要手动删
vcs/下某个仓库目录来“强制更新”——这只会让下次构建变慢；真正要更新的是composer.lock和对应的 Git commit
VCS 缓存不是“设了就一劳永逸”的开关，它和 composer.lock、Git commit hash、Docker 构建上下文三者强绑定。最容易被忽略的是：**缓存目录存在 ≠ 缓存有效**，只有当 lock 文件中记录的 hash 在缓存 clone 的 reflog 里能找到，才算真正命中。
