答案是Composer默认只查packagist.org，私有包需在repositories显式声明且其packages.json含新版本元数据；常见原因包括配置错误、Satis未重建、lock文件锁定或dev分支未被收录。
私有包更新后，composer update 不拉新版本？不是缓存没清，也不是权限问题，大概率是 packages.json 没刷新，或者客户端压根没查你的私有仓库。
为什么 composer update 总是跳过私有包更新
Composer 默认只检查 packagist.org，除非你在项目 composer.json 的 repositories 里显式声明了私有源，且该源的 packages.json 已包含目标包的新版本元数据。常见错误包括：
-
repositories配置漏了、拼写错（比如写成"type": "git"而非"vcs"） - 私有仓库服务（如 Satis）没重建，
packages.json还停留在旧 commit 或旧 tag - 本地
composer.lock锁死了旧版本，composer update vendor/package时没加--with-dependencies导致依赖链卡住 - 私有包的
version字段在composer.json里写死为dev-master，但 Satis 默认不收录dev-分支，除非配置"require-dependencies": true或手动"require": { "vendor/package": "dev-master" }
Satis 构建时如何确保新 tag / branch 被收录
Satis 不会自动监听 Git 变更，必须手动触发 build 并确认扫描范围覆盖了新提交。关键看配置文件里的两个字段：
-
"require-all": true：只收录所有仓库中已打 tag 的稳定版本（v1.2.0），不收dev-分支 -
"require": { "vendor/package": "dev-main" }：明确指定分支，但要求该分支在 Git 仓库中存在且可被 Composer 解析（即有合法的composer.json） - 若想同时收
tags和dev-main，得写成：{"require": {"vendor/package": "dev-main || ^2.0"}} - 构建命令末尾加
-v参数，能看见 Satis 实际解析了哪些 commit 和 tag，避免“以为扫了，其实跳过了”
客户端如何强制重载私有仓库元数据
Composer 缓存的是 packages.json 内容，不是包本身。即使你改了 Satis 输出目录，客户端也可能用着旧缓存。安全做法是：
- 清空远程元数据缓存：
composer clear-cache（影响所有源） - 只清私有源：
composer config --unset repos.private，再重新config repositories.private composer https://packages.example.org - 临时绕过缓存验证：
composer update --no-cache，适合 CI 环境快速验证 - 检查是否真从私有源加载：
composer show -p vendor/package，输出里source行应显示你的私有域名，而非https://api.github.com/...
分发时如何让团队立刻感知更新
靠人手动跑 composer update 不现实。真正可控的做法是把版本变更和仓库刷新绑定进流程：
- Git Tag 推送后，用 webhook 触发 Satis 构建（例如 GitHub Action 中执行
php bin/satis build satis.json web/） - 在私有包的
composer.json里加"archive": { "exclude": ["/tests/", "/docs/"] }，减小分发体积，加快install - 给每个私有包加
"homepage"和"support"字段，方便团队查文档或提 issue，避免“这个包谁维护？新版改了啥？”类问题反复出现 - 别依赖
dev-master长期上线——Satis 默认不索引它，且 Composer 安装时可能因 hash 变动导致重复下载，实际使用中建议用^x.y或具体 tag
最常被忽略的一点：Satis 生成的 packages.json 是静态文件，没有服务端逻辑。如果你改了配置但没重新 build，或者 build 时用了错误的 satis.json 路径，那客户端看到的永远是旧快照。
