Composer的path仓库专为本地开发调试设计，需同时满足：type为"path"、url是含合法composer.json的相对路径（不以/结尾）、本地包name与require完全一致，否则静默忽略。
直接说结论：Composer 的 path 仓库不是“装个包”用的，而是专为“边改本地包、边在主项目里实时验证”的开发调试场景设计的。配错一个字段、路径多一个斜杠、name 大小写不一致，它就静默跳过，连错误都不报——这不是 bug，是它的默认行为。
怎么让 Composer “看见”你的本地包
关键不在 composer require，而在主项目 composer.json 的最外层 repositories 字段必须显式声明：
-
type必须是"path"（不是"package"，也不能漏写） -
url必须指向一个**含合法composer.json的目录**，且是相对于主项目根目录的路径（如"../my-utils"），不能以/结尾 - 该本地目录下必须有 Git 仓库（至少
git init && git add . && git commit -m "init"），否则dev-main这类分支名无法解析 - 本地包的
composer.json中name字段必须和require里写的**逐字一致**："acme/utils"≠"Acme/utils"≠"acme_utils"
为什么 composer require vendor/name:dev-main 总报 “Could not find package”
根本原因：Composer 根本没读到你配的 path 仓库。常见失效点：
-
repositories被写进了require、config或其他嵌套字段里，它必须在composer.json最外层（和require同级） - 路径用了
~、./或绝对路径（path类型只接受相对路径；若要用绝对路径，得用composer config repositories.xxx命令写入全局配置） - 本地包目录下
composer.json有语法错误（比如尾逗号、单引号、中文引号），Composer 会直接忽略整个仓库 - 执行命令时当前工作目录不是主项目根目录，导致相对路径解析错位
怎么确保改代码立刻生效（symlink 模式）
默认情况下，Composer 对 path 仓库是复制（copy）行为。要变软链，必须满足三个条件同时成立：
- 主项目
composer.json的repositories条目中包含"options": {"symlink": true} - **本地包自己的
composer.json里也必须有"options": {"symlink": true}**（这是最容易漏的） - Windows 用户必须以管理员身份运行终端；Docker 需加
--cap-add=SYS_ADMIN并确认挂载支持 symlink
验证是否成功：运行 ls -la vendor/vendor/name（Linux/macOS）或 dir vendor\vendor\name（Windows），看到 -> 或 JUNCTION 才算真链接上了。
CI/CD 和 Docker 里为什么总失败
path 是纯开发期机制，上线环境不该存在。CI 构建机没有你的 ../my-pkg 目录，composer install 会直接跳过或报错。Docker 容器内即使挂载了宿主机目录，也常因权限或文件系统限制导致 symlink 创建失败，且无提示。真正安全的做法是：在 CI 流程中移除 path 配置，改用 Packagist 或私有仓库发布正式版本；本地开发才启用 path + symlink。
