私有库必须声明为repository，否则composer install无法识别；需在composer.json中配置repositories字段，类型匹配来源（path或vcs），且require与repositories缺一不可。
私有库必须声明为 repository，否则 composer install 根本看不到它
Composer 默认只认 packagist.org，本地路径或私有 Git 仓库不加配置就是“不存在”。哪怕包的 name 和 version 完全合法，require 也会报 Could not find package xxx。
实操建议：
- 在项目根目录
composer.json的顶层加repositories字段，类型必须匹配实际来源 - 本地路径用
{"type": "path", "url": "./packages/my-package"}，注意url是相对路径，且目标目录下必须有合法的composer.json - 私有 Git 仓库用
{"type": "vcs", "url": "git@github.com:myorg/private-package.git"}，确保当前机器能 SSH 免密访问 - 不要把私有库写进
repositories却漏掉require，或者反过来 —— 两者缺一不可
path 类型仓库会自动软链接，但只在开发环境生效
用 "type": "path" 加载本地包时，Composer 不复制文件，而是创建符号链接（Linux/macOS）或 junction（Windows）。这省空间、改即生效，但上线部署时会崩。
常见错误现象：
- 线上
composer install --no-dev失败，提示Source path ./packages/my-package does not exist - CI/CD 流水线里找不到本地路径，因为构建机根本没有那个目录
实操建议：
- 仅在
dev环境启用path类型，生产环境切回vcs或package类型 - 用
config.platform或不同环境的composer.json变体来隔离，别指望一个配置打天下 - 如果硬要打包发布，先
composer archive打 zip，再配"type": "package"指向该 zip URL
vcs 私有仓库需提前认证，且分支名必须带 dev- 前缀才能被识别为开发版
Git 仓库里的分支默认不被 Composer 当作版本。比如你 push 了 feature/login，直接 "my/package": "dev-feature/login" 会报 Could not find package...。
原因在于 Composer 对 VCS 包的版本解析规则：只有 dev-xxx 形式的分支名才被识别为 dev 版本；main、master、1.2 等会被当 stable 版本处理，要求对应 composer.json 中有明确 version 字段（通常不该写）。
实操建议：
- 开发阶段统一用
dev-main或dev-develop分支，require 时写成"my/package": "dev-main" - SSH 认证失败时，
composer update卡住或报Failed to clone git@...，检查ssh-add -l是否已加载 key - HTTP(S) 私仓需在
auth.json里配 token：{"http-basic": {"gitlab.example.com": {"username": "token", "password": "PAT..."}}}
composer.lock 会锁定私有库的实际 commit hash，换机器可能拉不到相同代码
私有 VCS 库一旦被安装，composer.lock 就会记下具体 commit，下次 install 严格按这个 hash 拉取。但如果原仓库被 force-push 覆盖了该 commit，或者新机器没权限访问原始 Git 地址，就会失败。
这不是 bug，是设计使然 —— 但容易被忽略。
实操建议：
- 团队内禁止对已发布的私有分支 force-push，尤其
main或dev-* - CI 构建前执行
git fetch --all，确保所有远程分支最新，避免因本地 repo 缓存导致 hash 不一致 - 若用
path类型，composer.lock里记录的是 symlink 路径，换机器后该路径失效，此时应删 lock 文件重装（仅限开发环境）
