生产环境私有仓库配置必须显式禁用packagist.org、通过COMPOSER_AUTH注入凭据、确保Satis MIME正确及Git tag发布，否则composer install将静默失败或拉错包。
生产环境配置私有仓库，不是“加个 repositories 就完事”，而是必须切断对 packagist.org 的任何依赖、确保认证不落地、所有路径可复现且无交互——否则上线时 composer install 会静默失败或拉错包。
项目 composer.json 必须显式禁用 packagist.org
哪怕私有源完全正常，只要没关掉官方源，Composer 就会在找不到包时 fallback 到 packagist.org，导致超时、拉取公开版本、甚至因 DNS/TLS 问题卡死。
-
"repositories"数组里必须包含你的私有源（"type": "composer"或"type": "vcs"），且 URL 以/结尾（如"https://packages.internal/"） - 必须显式声明
"packagist.org": false，写在repositories同级位置，不是子字段 - 不要留空数组或注释掉官方源——Composer 不识别注释，会当它不存在而自动启用默认源
auth.json 不能放项目里，必须走环境变量
生产环境禁止文件落地凭据。把 auth.json 放进项目根目录或挂载到容器里，等于把 Git 凭据暴露在代码树或镜像层中。
- CI/CD 中统一用
COMPOSER_AUTH环境变量注入 JSON 字符串，例如：{"http-basic":{"gitlab.example.com":{"username":"token","password":"abc123..."}}} - 确保该变量在
composer install执行时已加载（Kubernetes 中用envFrom或env；Docker 中用--env） - 如果用 SSH 克隆，私钥应通过
ssh-agent注入，而非复制密钥文件
Satis 静态仓库必须托管在 Web 服务下，且 MIME 正确
satis build 只生成文件，不启动服务。生产环境若直接用 file:// 或未配置 MIME，packages.json 会被浏览器或 Composer 当作文本下载，导致解析失败。
- Nginx 配置里必须声明
types { application/json json; }，否则返回text/plain，Composer 拒绝解析 - URL 路径要与
satis.json中的"homepage"完全一致，且结尾带/（"https://packages.internal/"✅，"https://packages.internal"❌） - dist ZIP 文件路径（如
dist/vendor/pkg/abcd123.zip）必须能被 Web 服务器直接 GET，不能被location规则拦截或重写
vcs 类型下，tag 是唯一版本依据
生产环境严禁用 "dev-main" 或 "dev-master"，也别信私有包自己 composer.json 里的 "version" 字段——它在 vcs 模式下完全被忽略。
- 所有发布版本必须打 Git tag，格式严格遵循语义化（如
v1.0.0、1.2.3），不能含空格或大写字母 -
require中写"myorg/pkg": "^1.0"，Composer 实际查的是远程仓库的 tag 列表，不是本地文件 - CI 发布流程必须包含
git push --tags，漏掉这步，composer update就永远看不到新版本
最容易被忽略的是：Satis 构建后不会校验 packages.json 是否真能被外部访问，也不会检查 dist ZIP 是否可下载——这些都得人工 curl 验证，否则上线第一分钟就失败。
