私有仓库本身不解决协作问题，仅标准化“包在哪”；真正影响体验的是repositories声明方式、认证机制和同步策略是否贴合团队工作流。
好用，但前提是配置正确、权限清晰、源类型匹配真实需求。私有源本身不解决协作问题，它只是把“包在哪”这个物理问题标准化了；真正影响体验的，是 repositories 声明方式、认证机制和同步策略是否贴合团队实际工作流。
为什么 composer require 会静默失败
这是最常踩的坑：私有包根本装不上，但错误信息只有 Could not find package，没有任何提示指向配置问题。
-
repositories必须写在你要运行composer require的那个项目的composer.json顶层，而不是私有包自己的composer.json - 数组格式不能错：
"repositories": [{"type": "composer", "url": "https://your-private-repo.com"}]—— 写成对象（{"my-repo": {...}}）或漏掉type都会失效 - URL 必须可被 Composer 协议识别：Satis 类型必须以
/packages.json结尾；Private Packagist 或 packagist-mirror 则需返回符合 Packagist 协议的元数据接口 - 如果用了 HTTPS 私有源但没配
auth.json，Composer 不报认证错误，而是直接跳过该源继续往下找，最终因没匹配到包而失败
path 类型仓库适合什么场景
type: "path" 看起来最简单，但它的适用边界非常窄——只适合本地开发联调，不是私有源方案。
- 它不生成
packages.json，所以无法支持语义化版本约束（如"^1.2"），只能按目录名硬匹配 - 路径必须是绝对路径或相对于
composer.json的相对路径，且目录下必须有合法的composer.json - CI/CD 流水线里几乎不可用：一旦构建机上没有这个路径，整个安装就崩
- 多人协作时，A 机器上的
./packages/my-utils和 B 机器上的路径很可能不一致，导致依赖解析结果不同
如何让私有包和公共包共存不冲突
关键不在“能不能”，而在“谁先被查”。Composer 按 repositories 数组顺序从上到下扫描，第一个命中即停。
- 把私有源放在数组最前面，避免公共包覆盖内部同名包（比如你们也叫
monolog/monolog，但实现不同） - 不要把 Packagist 官方源写进
repositories—— 它默认就在最后，显式声明反而可能干扰默认行为 - 若使用 Satis，确保其
satis.json中的require字段只包含你明确要同步的包，否则会拉取大量无关元数据，拖慢composer update - 对内部高频更新的包，建议用
dev-main或dev-develop分支 +"minimum-stability": "dev"，避免每次发版都要改composer.json版本号
真正卡住团队的往往不是搭建难度，而是权限和流程断层：比如 Git 仓库开了读写权限，但 Satis 同步脚本没权限拉取 private tag；或者 CI 里用 COMPOSER_AUTH 注入凭据，但本地开发忘了配 auth.json，导致环境行为不一致。这些细节比选型更决定私有源能否长期跑下去。
