答案是VCS缓存目录属主错配，需用sudo chown -R $USER:$USER $(composer config --global cache-dir)/vcs修复；若在WSL的/mnt/c/下则须迁移缓存至WSL原生路径。
composer update 报 Permission denied 且路径含 vcs/
看到错误里有 vcs/ 字样（比如 Writing cache file ~/.composer/cache/vcs/https---github.com-xxx-yyy.git），基本可以确定是 VCS 缓存目录权限错配，不是 ZIP 包损坏或 metadata 过期。VCS 缓存用于存储 Git 克隆的 bare repo，Composer 会反复读写它，一旦属主不对，composer update 就会在拉取私有包时卡住。
立刻检查：ls -ld $(composer config --global cache-dir)/vcs。如果属主不是当前用户（$(whoami)），就别清缓存，先修归属：
- Linux/macOS：运行
sudo chown -R $USER:$USER $(composer config --global cache-dir)/vcs - Windows：用
icacls重设 ACL，命令是icacls "%APPDATA%\Composer\Cache\Vcs" /grant "$env:USERNAME:(OI)(CI)F" /t（PowerShell 管理员模式） - 别删
vcs/目录本身——重 clone 成本高，且可能丢失 shallow clone 状态；只修权限
git clone 失败并提示 Permission denied (publickey)
这不是 Composer 权限问题，而是 Git 层鉴权失败。Composer 调用 git clone 时若没拿到 SSH key，就会报这个错，但错误被包装成 Permission denied，容易误判为文件系统权限。
验证方式：手动进 vcs/ 对应子目录（比如 ~/.composer/cache/vcs/https---github.com-user-repo.git），执行 git remote get-url origin，看是否是 git@github.com:user/repo.git 这类 SSH 地址。
解决路径分三类：
- SSH 地址 → 确保
ssh-add -l能列出对应 key，且~/.ssh/config里没写错IdentityFile - HTTPS 地址 → 检查
auth.json是否配置了该域名的http-basic凭据，格式必须是{"http-basic": {"gitlab.example.com": {"username": "u", "password": "p"}}} - 私有 GitLab/Gitea → Composer 不支持 OAuth2 Bearer Token 自动注入，得换 HTTPS + token 方式，把 token 当 password 填在
auth.json里
WSL 下 vcs/ 缓存写入失败
WSL 用户如果把项目放在 /mnt/c/ 下，又让 Composer 把 vcs/ 缓存也写到同一挂载点，就会遇到“权限拒绝”但 ls -ld 显示一切正常的诡异现象——这是 WSL 的 Windows 文件系统桥接限制，chmod 和 chown 在 /mnt/c/ 下全是假动作。
必须把全局缓存移到 WSL 原生路径：
- 执行
composer config -g cache-dir "/home/$USER/.composer-cache" - 再手动创建并授权：
mkdir -p /home/$USER/.composer-cache && chmod 755 /home/$USER/.composer-cache - 删掉旧缓存：
rm -rf /mnt/c/Users/*/AppData/Roaming/Composer/Cache/Vcs（Windows 侧）和rm -rf ~/.composer/cache/vcs（WSL 侧）
之后所有 vcs/ 操作都在 ext4 分区上，不再受 Windows ACL 干扰。
vendor/ 中私有包更新后仍用旧 commit
这常被当成权限问题，其实是 VCS 缓存没刷新导致的“逻辑 stale”。Composer 默认复用 vcs/ 里已有的 bare repo，不主动 git fetch，所以即使远程分支已更新，composer update 仍检出旧 commit。
强制刷新方法只有两个：
- 删对应缓存目录：
rm -rf $(composer config --global cache-dir)/vcs/https---github.com-user-repo.git（Linux/macOS）或 PowerShell 中Remove-Item "$env:APPDATA\Composer\Cache\Vcs\https---github.com-user-repo.git" -Recurse -Force - 加
--prefer-source参数重装：composer update vendor/package --prefer-source，它会绕过缓存、直接 clone 新 repo
注意：composer clear-cache 不清理 vcs/，这点和 files/ 完全不同，容易漏掉。
