核心是将私有仓库地址以 type: "composer" 添加到项目 composer.json 的 repositories 中，并确保 Satis 已 build、packages.json 可访问、包名匹配且 minimum-stability 正确，再清缓存执行 composer update。
怎么让 composer install 拉到私有包
核心就一条：把私有仓库的地址加进项目的 composer.json 的 repositories 里，且类型得是 vcs 或 composer。Satis 生成的是标准 Composer 仓库（type: composer），所以优先配后者。
常见错误是只改了全局 config.json，但项目里没声明——Composer 默认只认项目级配置里的仓库，不自动继承全局的。
- 项目
composer.json中添加：
"repositories": [
{
"type": "composer",
"url": "https://your-satis-domain.com"
}
],
"minimum-stability": "stable",
"prefer-stable": true
-
url必须可被 Composer 直接访问（比如能 curl 通），且返回的是合法的packages.json - 别漏掉
minimum-stability—— 私有包如果没有明确打stable标签，require时会报 “could not find package” - 改完后运行
composer clear-cache再composer update，否则可能读缓存旧元数据
为什么 composer require 找不到私有包
不是包名写错了，就是仓库没生效，或者包本身没被 Satis 索引进去。
Satis 不是实时同步的——它只在你手动执行 php bin/satis build 后，才扫描 Git 仓库、读 composer.json、生成静态 JSON。如果私有包刚 push 了新 tag，但没 rebuild Satis，那 Composer 就真找不到。
- 确认包的
name字段和require时写的完全一致（包括 vendor 名，大小写敏感） - 用浏览器打开
https://your-satis-domain.com/packages.json，搜包名，看是否存在 - 检查 Satis 配置里的
repositories列表是否包含该包的 Git 地址，且协议可用（如https://而非git@） - 如果用了 GitLab/GitHub 私有库，确保 Satis 机器有对应 SSH key 或 Personal Access Token 权限
用 Satis 时怎么避免 build 失败或漏包
失败主因是权限、网络或路径问题；漏包常因为分支/标签没匹配上 Satis 的 require-all 或 require-dependencies 规则。
Satis 默认只抓 master 和带语义化版本 tag（如 v1.0.0）的 commit。如果你用 dev-feature 分支或 1.0.0-rc1 这种 tag，得显式配置 require-dependencies 或自定义 branches。
- build 命令必须在 Satis 配置目录下运行：
php bin/satis build satis.json web/，web/是输出目录，别写错路径 - 确保
satis.json里output-dir有写权限，且磁盘空间够（尤其包多时，临时克隆很吃空间） - 加
"archive": {"directory": "dist", "format": "tar", "skip-dev": true}可生成压缩包，加快下游 install 速度 - CI 中自动 build 时，记得设
COMPOSER_HOME环境变量指向可写目录，否则可能卡在 auth 验证
私有包更新后 Composer 还拉旧版怎么办
不是缓存没清，就是 Satis 没重新 build，或者本地锁文件 composer.lock 锁死了版本。
Composer 安装时优先按 composer.lock 里的 exact commit hash 或 version 拉，哪怕远程已有新版。这点和 npm 不同，容易误以为“更新了 Satis 就自动生效”。
- 先确认 Satis 已成功 build，且
packages.json里对应包的version或dist.reference是新值 - 删掉
composer.lock和vendor/，再跑composer install（适合验证） - 日常更新用
composer update vendor/package-name，比全量 update 更可控 - 如果包是
dev-master，注意 Satis 默认不索引dev-分支，得在satis.json里加"require-dependencies": true或显式列"branches": ["dev-master"]
最常被忽略的是：Satis build 日志里出现 Skipping repository ... no composer.json found，说明 Git 仓库根目录没有 composer.json，或者文件权限不对——这种包压根不会进 packages.json，后面所有操作都白搭。
