path仓库类型不能用于生产环境，因其依赖本地文件系统硬链接，不生成元数据、不校验shasum、不支持版本约束解析，ci构建或容器部署时路径不存在会导致composer install失败，仅限本机开发调试。
为什么 path 仓库类型不能用于生产环境
path 类型仓库（如 {"type": "path", "url": "../my-private-lib"}）本质是本地文件系统硬链接，Composer 会直接 symlink 或 copy 源目录内容到 vendor/。它不生成元数据、不校验 shasum、不支持版本约束解析（比如 "^1.2" 会被忽略，强制用当前 HEAD），更无法被其他机器复现。CI 构建时若未同步该路径，composer install 直接失败；部署到容器或远程服务器时，路径根本不存在。
- 仅限本机开发调试，比如快速验证一个尚未提交的私有库修改
- 绝对不要出现在
composer.json的正式提交中，尤其不能进主分支 - 若误提交，别人
composer install会报错：Could not find package vendor/name at any version，因为 Composer 在本地路径找不到就彻底放弃，不会 fallback 到其他仓库
path 仓库的正确写法与常见拼写错误
必须确保 url 是相对于项目根目录的**有效绝对路径或相对路径**，且目标目录下存在合法的 composer.json（含 name 字段）。路径末尾斜杠不能省略（../lib/ ✅，../lib ❌），否则 Composer 会静默忽略该仓库。
- 推荐写法：
{"type": "path", "url": "./packages/my-private-lib/"}（同级子目录） - 禁止写法：
{"type": "path", "url": "/home/user/my-lib"}（绝对路径 → CI 失败） - 禁止写法：
{"type": "path", "url": "packages/my-private-lib"}（缺末尾斜杠 → 不生效） - 包名必须严格匹配目标
composer.json中的name，大小写敏感，例如目标为"name": "acme/utils"，则require必须写"acme/utils": "*"
如何安全地从 path 过渡到真实私有仓库
开发阶段用 path 快速迭代没问题，但只要代码稳定、需要协作或上线，就必须切换成可复现的仓库类型（vcs 或 composer）。关键不是改 URL，而是补全三件事：
- 在私有 Git 仓库中打正式 tag（如
v1.0.0），并确保composer.json的version字段与之匹配（或留空让 Composer 自动推断） - 把
repositories中的path条目换成vcs，URL 改为git@...或https://... - 运行
composer update acme/utils --with-dependencies，强制重新解析版本约束，避免缓存旧的 symlink 行为 - 删掉
vendor/acme/utils和composer.lock中对应条目再重装，确认不再是 symlink 而是真实下载
CI/CD 中误用 path 的典型失败现象
最常出现的报错不是语法错误，而是静默行为异常：构建日志显示 Installing acme/utils (dev-main)，但实际没下载任何文件，vendor/acme/utils 是个空目录或残留的 symlink。根本原因是 CI runner 根本没有那个本地路径，而 Composer 又没报错退出。
- 检查点 1：CI 脚本开头加
ls -la ../my-private-lib，确认路径是否存在 - 检查点 2：执行
composer config --list | grep repositories，看是否真读到了path配置（有时因 JSON 格式错误被跳过） - 检查点 3：在 CI 中临时加
composer show acme/utils，若返回Package not found，说明仓库配置完全失效 - 真正可靠的方案是：CI 环境永远只认
vcs或composer类型，path仅保留在开发者本地的composer.json副本中，通过 .gitignore 排除
