私有仓库拖慢大型项目install，根本原因是Composer默认行为与私有源配置不匹配，导致重复解析、fallback失败及元数据膨胀；必须显式声明"packagist.org": false、确保URL末尾含/、启用type: composer后端仓库，并通过--optimize-autoloader、精简lock文件、排除非必要归档路径来优化。
为什么私有仓库在大型项目里反而拖慢 install
不是仓库本身慢，是 Composer 默认行为和私有源配置不匹配导致的重复解析、fallback 失败、元数据膨胀。典型现象：composer install 卡在 Resolving dependencies 阶段超过 30 秒，composer update 反复连 packagist.org 却报 Could not find package。
-
"packagist.org": false必须显式声明在composer.json根级，漏掉这一行，Composer 就永远优先查公共源，私有包再正确定义也无效 - 私有仓库 URL 末尾斜杠
/不可省略，https://artifactory.example.com/repo和https://artifactory.example.com/repo/在 Composer 内部会被视为两个不同源 - 若用 Satis 或 Artifactory 虚拟仓库，必须确保后端至少有一个
type: composer的本地/远程仓库被启用，Generic类型仓库无法提供 Composer 所需的packages.json接口
如何让私有包加载快且稳定
关键不在“下得快”，而在“不反复查、不瞎 fallback、不加载冗余 autoload”。实测中，autoload 优化和锁文件瘦身带来的收益远超网络加速。
- 加
--optimize-autoloader：把私有包的 PSR-4 映射转成 classmap，避免运行时遍历目录；但注意——若私有包内大量使用class_exists("{$prefix}".$name)这类动态拼接类名逻辑，classmap 会失效，需改用--classmap-authoritative或保留 PSR-4 - 定期运行
composer update --lock（不带包名）：压缩composer.lock中冗余字段，尤其清理掉已废弃的require-dev包残留元数据；大型项目 lock 文件从 12MB 降到 3MB 后，JSON 解析耗时下降 60%+ - 私有包的
composer.json中务必声明"archive": {"exclude": ["/tests", "/docs", "/examples"]}，否则 Satis 构建时会为这些路径生成哈希并写入 lock，徒增体积与校验开销
CI/CD 中私有仓库认证失败的硬核排查点
错误常表现为 Failed to clone https://gitlab.com/org/private.git 或 Authentication failed，但根本原因往往不在密钥本身。
- SSH 方式下，
auth.json无效——Composer 不读auth.json处理vcs类型仓库，只认系统 SSH agent 或~/.ssh/config中的Host别名配置 - HTTPS + PAT 方式下，token 权限不足：GitHub 需
repo，GitLab 需read_repository，Gitee 需勾选“代码”权限；且 token 必须写在auth.json的github-oauth或http-basic下对应域名键下，不能塞进gitlab-token这类自定义字段 - CI 环境未预装 Git：某些精简版 CI 镜像（如
php:8.3-cli-slim）默认不带git命令，vcs类型仓库会直接跳过，降级为dist模式失败，报错却显示 “package not found”
多个私有仓库共存时的优先级踩坑
不是“先写的先用”，而是“先命中先停”，但 only/exclude 规则会覆盖顺序逻辑，极易误判。
- 若两个私有仓库都配了
"only": ["acme/*"]，Composer 会按repositories数组顺序选第一个匹配的，第二个完全忽略——哪怕第一个仓库里acme/utils版本是旧的，也不会 fallback 到第二个 -
"exclude": ["monolog/monolog"]放在 Packagist 仓库配置里，能屏蔽公共源的 monolog，但若你同时启用了"packagist.org": false，这条 exclude 就彻底失效，因为 Packagist 根本没被加载 - Artifactory 虚拟仓库开启
Enable Default Deployment Repository是上传私有包的前提；没勾选时，composer publish会静默失败，日志只提示No repository configured for publishing，实际是虚拟仓库拒绝接收
真正卡住大型项目私有依赖的，从来不是带宽或磁盘，而是配置里一行缺失的 "packagist.org": false、一个少打的斜杠、一次没清理的 dev 依赖残留——这些地方不显眼，但改完立刻见效。
