path仓库必须写入repositories字段而非config指令，因config仅控制行为参数而不参与包发现；需在composer.json根级配置type: "path"和本地url路径，并确保目标含有效composer.json且有name声明。
“path 仓库”不能通过 config 指令设置，必须写进 repositories 字段 —— 这是常见误解的根源。
为什么 config 不能配 path 仓库
config 指令只控制行为参数（如 bin-dir、sort-packages、github-oauth），不参与包发现逻辑。而 path 是一种 repository 类型，属于依赖源定义，必须出现在 repositories 数组里，且需配合 type: "path" 和 url（本地路径）。
常见错误现象：composer config repositories.my-local path /path/to/pkg 看似执行成功，但 composer require vendor/name 仍报 Package not found —— 因为该命令根本不会被解析为仓库配置，Composer 直接忽略。
-
config只写入config字段（项目级）或全局config.json，它不碰repositories -
repositories必须手动写进composer.json根级，或用composer config repositories.xxx命令（注意：这不是config子命令，而是config对repositories的特殊支持） - 手写
repositories时，url值必须是相对路径（如../my-package）或绝对路径（如/home/user/my-package），不能带file://前缀
正确添加 path 仓库的两种方式
推荐直接编辑 composer.json，清晰可控；若需脚本化，用 composer config 的 repositories 专用语法。
- 手动编辑：
"repositories": [{"type": "path", "url": "../my-local-pkg"}]，放在composer.json根对象下，与require同级 - 命令行添加（仅限 Composer ≥2.2）：
composer config repositories.local-path '{"type":"path","url":"../my-pkg"}'—— 注意单引号包裹 JSON，且键名是repositories.xxx，不是config.xxx - 加
--file composer.json可指定非默认文件，但不改变写入位置逻辑 - 添加后必须运行
composer update --lock或composer install才能触发仓库扫描
path 仓库生效的关键细节
即使 repositories 配对了，path 仓库也常因路径或结构问题静默失效。
-
url路径必须指向含有效composer.json的目录，且该文件中必须声明name（格式为vendor/name），否则 Composer 不识别为可安装包 - 路径区分大小写（Linux/macOS）；Windows 下虽不敏感，但建议保持一致
- 如果目标目录有
composer.lock，它会被忽略；path仓库始终读取源码目录下的composer.json - 多个
path仓库按repositories数组顺序匹配，靠前的优先；可用"packagist": false关闭 Packagist 默认源避免冲突
容易被忽略的权限与符号链接问题
在 CI 或 Docker 环境中，path 仓库最常卡在这类底层问题上，错误提示却极不明确（比如直接报 Could not find package）。
- 宿主机挂载到容器的路径，必须确保 PHP 进程用户（如
www-data）有读取权限，否则扫描失败且无日志 - 符号链接（symlink）默认被跳过；需在
url中使用真实路径，或启用"options": {"symlinks": true}（Composer ≥2.5） - Windows WSL 用户要注意路径格式：用
/mnt/c/Users/xxx/pkg而非C:\Users\xxx\pkg，否则is_dir()检查失败 - IDE（如 PhpStorm）可能缓存旧的
vendor映射，改完repositories后需刷新索引或重启
