Composer私有化部署需拆分源角色：私有源放repositories数组首位，公共镜像次之，末尾加{"packagist": true}兜底；全局config -g repo.packagist仅代理packagist.org元数据，不作用于私有源，且会被项目级repositories完全屏蔽。
私有化部署中，Composer 既要拉官方包加速，又要能稳定加载租户私有包——不能只配一个镜像源，也不能靠“试错式 fallback”。关键在于：把私有源和公共镜像按角色拆开，用 repositories 数组显式声明顺序，再禁用隐式兜底。
为什么 composer config -g repo.packagist 不够用？
这条命令只能替换 packagist.org 的代理地址，但对私有包无效。它不处理 repositories 字段，也不影响你项目里声明的私有源。更麻烦的是：一旦你在 composer.json 里写了 "packagist.org": false，全局配置就被完全屏蔽了。
- 全局镜像只接管
packagist.org元数据请求，不接管任何type: "composer"私有源 - 私有包必须在项目级
composer.json的repositories数组里显式列出，且 URL 必须以/结尾 - CI/CD 构建机若以非 root 用户运行，
-g配置可能写到错误用户目录下，导致生效失败
repositories 数组怎么写才不丢包？
必须是索引数组，每个元素独立、含 type 和 url，顺序即查找顺序。混用私有源和公共镜像时，把私有源放前面，公共镜像放后面，末尾加 {"packagist": true} 做元数据兜底（可选）。
- ✅ 正确结构：
"repositories": [ {"type": "composer", "url": "https://pkgs.internal/artifactory/api/composer/internal/"}, {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}, {"packagist": true} ] - ❌ 错误写法：
"repositories": { "internal": { ... }, "aliyun": { ... } }—— Composer 只读第一个键值对，其余静默忽略 - 私有源 URL 少斜杠 → 拼成
https://pkgs.internal/packages.json（404）；多斜杠如//也会触发解析异常 -
{"packagist": true}是特殊语法，不是 URL，只查元数据，不下载 ZIP，适合防新包漏索引
私有源认证失败常见原因
报 401 Unauthorized 或 could not find package，大概率不是网络问题，而是认证链断在某个环节。
-
auth.json必须放在项目根目录，或COMPOSER_AUTH环境变量里；~/.composer/auth.json在容器或 CI 中常不可见 - Token 权限必须包含
read:packages（GitLab）或read_package_registry（GitHub），仅api权限不够 - Artifactory/Nexus 的 Composer 仓库路径必须带
/api/composer/xxx/后缀，且启用Enable Token Authentication选项 - 如果用了 Satis，
satis.json里的repositories若含私有 Git 地址，构建前得先git config --global credential.helper store并缓存 token
交付包里哪些文件必须打包进去？
别指望客户现场手动配。租户私有化部署包里，这四样缺一不可：
- 项目根目录下的
composer.json，含正确repositories数组和"packagist.org": false - 同目录的
auth.json，格式为{"http-basic": {"pkgs.internal": {"username": "...", "password": "..."}}} -
composer.lock文件——它固化了所有包版本和 dist URL，避免 install 时重新解析 - 若用 Artifactory/Nexus，确保
dist目录下 ZIP 包路径与packages.json中dist.url完全一致（含协议、域名、路径、哈希）
少一个，交付现场就可能卡在 Resolving dependencies 或 file_get_contents(): failed to open stream。最隐蔽的问题是 auth.json 权限不对：非 root 用户运行时，chmod 600 auth.json 才安全，否则 Composer 会跳过读取。
