如何在 Composer 中处理那些既发布在 Packagist 又发布在私有仓库的包？

composer 默认优先使用 Packagist，要强制使用私有版本需禁用默认源、显式声明私有仓库并置顶，或用 type: package 精确指定分支/commit，配合 config 临时覆盖及 show -v 验证源地址。

当一个包既在 Packagist 上公开发布，又在私有仓库（如 Satis、private Packagist 或 git 仓库）中托管时，Composer 默认会优先使用 Packagist。若你希望强制使用私有版本（比如带内部补丁、定制分支或未同步到 Packagist 的开发版），关键在于控制源解析顺序和显式声明仓库优先级。

明确配置私有仓库并设置优先级

Composer 按 repositories 数组中定义的顺序查找包，但 Packagist 是隐式默认源，排在所有显式仓库之后。要让私有仓库“赢过”Packagist，需禁用 Packagist 默认源，并显式添加它作为最后一个仓库：

• 在 composer.json 中设置 "packagist.org": false 禁用默认 Packagist
• 手动将 Packagist 加入 repositories 列表末尾
• 把你的私有仓库放在该列表靠前位置（如第一个）

示例配置：

{   "repositories": [     {       "type": "composer",       "url": "https://your-private-repo.com"     },     {       "packagist.org": false     }   ],   "require": {     "vendor/package": "^1.2"   } }

使用 repository-alias 或自定义 type: package 精确控制

如果私有版本只是某个公开包的特定分支或 commit，且不想影响其他依赖，可避免全局替换。这时可用 "type": "package" 声明一个“虚拟仓库条目”：

Mootion

Mootion是一个革命性的3D动画创作平台，利用ai技术来简化和加速3D动画的制作过程。

232

查看详情

• 直接指定包名、版本号、dist 源（如 Git URL + commit hash 或 ZIP 下载地址）
• 版本号建议用 dev- 前缀或自定义稳定性标记（如 "dev-my-patch": "dev-main#abc123"）
• 配合 "minimum-stability": "dev" 和 "prefer-stable": true 平衡稳定性

利用 composer config 临时覆盖（适合 CI/部署场景）

不修改项目 composer.json 时，可通过命令行注入私有源：

• composer config repositories.private composer https://your-private-repo.com
• composer config repo.packagist.org false
• 再运行 composer update vendor/package 即可生效
• CI 脚本中可组合使用，更新后自动还原（用 composer config --unset）

验证是否命中私有源

执行 composer show -v vendor/package 查看详细信息，重点关注：

• source 字段是否指向你的私有 URL 或 Git 仓库
• dist 中的 url 是否为私有域名或内部路径
• 运行 composer install -vvv 观察日志里 “Loading from cache” 或 “Downloading” 的源地址

基本上就这些。核心是打破“Packagist 优先”的默认行为，用显式声明+顺序控制+精准匹配来导向私有副本。不复杂但容易忽略细节。