团队异地协作时，composer.json 中严禁配置 type: "path" 仓库，因其路径仅本地有效、跨机器必然失效，且无版本管理；必须将 repositories 显式写入项目级 composer.json，并搭配私有 Packagist 或 Git VCS 实现安全共享。
团队异地协作时，composer.json 里不能写 type: "path"
本地路径仓库（path）只在你本机有效，异地同事的机器上根本不存在 ../packages/utils 这个路径。一提交 Git，CI 就报 Could not find package，不是配置错，是路径天然不跨机。
- 它不生成元数据，不走 HTTP，其他机器连“访问”这个动作都做不到
- Windows/macOS 路径大小写、空格、权限差异会直接导致
Source directory does not exist - 就算用符号链接绕过，也解决不了版本管理问题——没有 tag，没法回滚，也没法做分支隔离
真要本地快速验证？用 composer config repositories.local path "../packages/utils"，它只写进 ~/.composer/config.json，不进 Git，关掉也只需 composer config --unset repositories.local。
异地团队必须把源配置写进项目级 composer.json
全局配置（composer config --global）对 CI、新成员、Git 都不可见，等于没配。唯一可靠的方式，是把 repositories 显式写进项目根目录的 composer.json，让所有环境自动识别。
- 私有源必须放
repositories数组最前面，且显式保留{"type":"packagist.org", "url":"https://packagist.org"}作为兜底，否则 Composer 会跳过默认源 -
platform字段只能写在项目级配置里，比如"platform": {"php": "8.1.0"}，才能确保不同 PHP 版本下解析出一致的依赖树 - 别用
merge-plugin或脚本拼接多个composer.json——Composer 只读一个文件，其他字段会被覆盖或丢弃
跨地域项目一致性，首选官方源而非国内镜像
阿里云、腾讯云等国内镜像存在 5–30 分钟同步延迟，跨国团队各自拉取，可能装到不同 minor 版本，甚至一个拉到 v2.3.1，另一个还卡在 v2.3.0。这不是网络问题，是镜像机制决定的。
- 检查当前实际生效的源：
composer config --list | grep repositories，确认repositories.packagist.url是不是指向了已失效的旧镜像 - 如果必须用内网镜像，Satis 是轻量可行方案：它生成静态
packages.json和 ZIP 归档，扔到 Nginx 就能被全网访问；但注意它不支持实时同步，需手动php bin/satis build - 代理型镜像（如 packagist-mirror）适合需要秒级同步的场景，但部署和维护成本高得多
composer.lock 冲突本质是 PHP 环境不一致，不是文本合并问题
分支 A 在 PHP 8.2 下跑 composer update，分支 B 在 PHP 8.1 下跑，两者生成的 composer.lock 中 platform 字段不同，content-hash 必然冲突。Git 工具没法智能选哪个，因为两个都是合法快照。
- 解决方式不是手动改 lock 文件，而是先合并干净的
composer.json，再统一执行composer update --lock -
composer.lock必须提交，/vendor必须忽略，这是底线。CI 流程中永远用composer install，禁用update - 团队应约定专人负责升级依赖，并在测试通过后单独提交 lock 变更，避免多人同时触发更新
异地协作最难的从来不是“怎么连”，而是“怎么确保所有人看到的是同一份元数据”。路径、镜像、lock 文件这三处，任何一处靠“本地经验”或“临时绕过”，都会在 CI 或新成员接入时集中爆发。
