github actions 触发 satis 构建失败主因是 git 凭据缺失或 composer.json 含非法 version 字段；需配置 pat 认证、移除 version 字段、指定可写输出目录并加 --no-interaction 参数。
GitHub Actions 触发 Satis 构建失败怎么办
常见现象是 php bin/satis build 执行卡在 Git 克隆或报 Could not parse version constraint dev-main。根本原因不是脚本写错，而是 CI 环境里缺少 Git 凭据或目标仓库 composer.json 含非法 version 字段。
实操建议：
- 在 GitHub Actions 中显式配置 Git 认证：用
actions/checkout@v4并设token: ${{ secrets.PAT }}（PAT 需含repo权限） - 确保所有私有包根目录下的
composer.json不含"version"字段——Satis 依赖 Git Tag 推断版本，硬编码dev-main或1.0.0-beta会直接解析失败 - 构建命令必须指定输出目录且路径可写：
php bin/satis build satis.json public/，public/需提前mkdir -p - 加
--no-interaction参数避免交互阻塞流水线
如何让 Satis 只更新被推送的包
Satis 默认全量扫描 repositories 列表，但大型团队往往只需更新当前变更的包。它不支持真正意义上的“增量”，但可通过参数缩小范围。
实操建议：
- 在 workflow 中提取当前 tag 对应的包名（如
v1.2.0→your-vendor/your-package），传给构建命令：php bin/satis build satis.json public/ your-vendor/your-package - 若多个包共用一个仓库（如 monorepo），改用
--repository-url指向当前 push 的 Git URL：php bin/satis build --repository-url ${{ github.event.repository.clone_url }} satis.json public/ - 注意：该方式仍会重新扫描整个仓库的全部 Tag，但跳过其他
repositories条目，显著缩短耗时
客户端 composer install 仍连 packagist.org？检查这三点
即使你已在项目 composer.json 中添加了私有源，composer install 还是去外网拉包，说明配置未生效。问题几乎都出在客户端侧。
实操建议：
- 确认
repositories数组中包含"packagist.org": false——漏掉这一行，Composer 会把私有源当 fallback，永远不查它 - 私有源
url必须以/结尾，例如"https://packages.internal/"，少斜杠会导致 404 且静默降级 - 运行
composer config --list | grep repositories，检查是否被全局配置覆盖；如有，用composer config --unset repos.packagist清除干扰项
Artifactory 用户注意：type 必须是 composer，不是 generic
错误日志显示 Invalid repository type 或元数据解析失败，90% 是因为 Artifactory 仓库类型选错了。Generic 类型完全不兼容 Composer 协议。
实操建议：
- 创建仓库时，“Package Type”下拉框必须手动选
composer，不能依赖默认值 - Virtual 仓库的 “Repositories” 列表里，只勾选已启用
composer协议的 Local/Remote 仓库 - Remote 仓库的 “URL” 填的是上游地址（如
https://packagist.org），不是你自己的 Git 地址；若要代理私有包，需用 Local 类型 +composer包类型
composer create-project your-vendor/your-package，否则上线后才发现 404 或 autoload 失败，就晚了。
