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" 声明一个“虚拟仓库条目”：
- 直接指定包名、版本号、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.comcomposer 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 优先”的默认行为，用显式声明+顺序控制+精准匹配来导向私有副本。不复杂但容易忽略细节。
