私有仓库必须用 Satis 或付费私有 Packagist 实例；Satis 仅通过 Git tag 解析语义化版本（需 v 前缀），且 satis.json 必须显式声明 vcs 类型 URL；CI 需在 tag 推送后自动构建并确保 packages.json 可 HTTP 访问。
私有仓库必须用 Satis 或私有 Packagist 实例
Composer 官方 packagist.org 只索引公开仓库，私有 Git 仓库（如 GitHub 私有库、GitLab 内网库）提交到官方 Packagist 会直接报 Repository not found。你无法绕过这个限制——它不是配置问题，而是服务策略。真实可行的方案只有两个：satis（静态生成）或自建 packagist.com 私有实例（需付费）。Satis 更常用，轻量、开源、可完全托管在内网。
打 tag 是唯一触发语义化版本的方式
Satis 不监听分支推送，只通过 Git tag 解析版本。你 push 一个 v1.0.0 标签，Satis 构建时才会生成对应版本元数据；push main 分支或 dev-feature 分支不会产生任何新版本。常见错误是误以为改完 composer.json 就算发布，其实它完全被忽略。
-
git tag -a v1.0.0 -m "stable release"—— 必须带v前缀，且符合语义化规范（v2.1.3-beta.1✅，1.0.0❌） -
git push origin v1.0.0—— 不要用git push --tags，容易漏推，尤其当本地有多个未同步 tag 时 - tag 对应的 commit 中，
composer.json必须已存在且合法（含name、type、autoload），否则 Satis 构建会跳过该版本
satis.json 配置里必须显式声明 VCS 类型和 URL
Satis 不自动发现仓库，所有私有包都得手动列在 satis.json 的 repositories 数组中。URL 必须是可直连的 Git 地址（支持 SSH 或 HTTPS），且类型明确设为 vcs。如果用 Gitee 或自建 GitLab，URL 格式不对（比如少了 .git 后缀或协议不匹配），构建时会静默跳过该仓库，不报错但也不生成包信息。
示例关键段落：
{
"repositories": [
{
"type": "vcs",
"url": "git@git.internal.company:team/utils-lib.git"
}
],
"require-all": true,
"archive": {
"format": "zip",
"skip-dev": true
}
}
CI 流水线里必须调用 php satis build 并推送生成物
仅靠本地运行 php satis build satis.json public/ 是不可持续的。生产环境必须接入 CI（如 GitHub Actions/GitLab CI），在检测到 tag push 事件后自动执行构建。构建输出目录（如 public/）需同步到 Web 服务器可访问路径，且确保 packages.json 和 dist/ 下的 zip 包都能被 curl 直接获取——否则项目执行 composer install 时会卡在 Could not fetch。
- 构建前建议加
composer validate检查目标仓库的composer.json - 构建后建议用
curl -I https://packages.internal.company/packages.json验证 HTTP 状态码为 200 - 不要把
satis.json放进私有包仓库里，它属于仓库管理配置，应独立存放
composer require your-vendor/your-package:^1.0 即可命中。最容易被忽略的是 tag 名格式与 CI 构建后的 HTTP 可达性验证——这两点出问题，整个流程就卡死，且错误表现往往只是“找不到包”，而非具体原因。 
