Composer Path仓库的核心是让本地修改实时生效，前提是symlink真正启用且autoload映射指向真实路径；若require报“Could not find package”，根本原因是repositories未在主项目composer.json中正确配置。
Composer Path仓库不是“让本地包装得上”，而是“让本地改动能立刻反映到主项目里”——前提是 symlink 真正生效，且 autoload 映射指向的是你正在编辑的真实文件路径。
为什么 composer require vendor/name:dev-main 会报 “Could not find package”
根本原因不是网络或权限，是 Composer 根本没“看见”你的本地目录。它只在主项目 composer.json 的 repositories 数组里找源，require 字段只声明“我要谁”，不负责“去哪找”。
-
repositories必须写在主项目（即你正在开发的那个项目的）composer.json里，不能写在本地包自己的composer.json中 -
url必须是相对路径（如"../my-package"），绝对路径在 Windows 上极易静默失败（盘符、反斜杠、空格都会中断） - 本地包目录下必须有合法的
composer.json，且其中name字段（如"acme/utils"）要和require里写的完全一致（大小写敏感、分隔符只能用短横线-） - 版本约束必须用
dev-main、dev-develop这类分支名，不能写1.0.0—— path 源下 Composer 忽略version字段，只认当前 Git HEAD 所在分支
改了本地包代码，为什么主项目里没变化
默认行为是复制（copy），不是链接（symlink）。你改了 ../my-package/src/Helper.php，vendor/acme/utils/Helper.php 还是旧文件。
- 关键不在主项目配
"symlink": true，而在于本地包自己的composer.json是否声明了"options": {"symlink": true}。缺这句，Windows 或 Docker 下常静默 fallback 到 copy - 执行
composer update acme/utils（不是dump-autoload）才会重建 symlink - 验证是否成功：
ls -la vendor/acme/utils（Linux/macOS）应显示箭头指向源目录；Windows 用dir vendor\acme\utils看是否为“快捷方式”类型 - Windows 需开启开发者模式或以管理员权限运行命令行，否则 symlink 创建失败且无提示
autoload 不生效，不是 Composer 没加载，而是映射没更新
Path 仓库让包“存在”，但类能否被 new 或 use，取决于 autoload 映射是否包含它的真实路径。
- 即使本地包
composer.json写了"psr-4": {"Acme": "src/"}，主项目也不会自动继承这个映射 ——composer dump-autoload -o必须手动执行 - Xdebug 断点失效？检查 IDE 里打开的文件路径是否与磁盘真实路径一致（比如 IDE 打开的是
vendor/acme/utils/src/...，但实际代码在../my-package/src/...） - 如果用了
"autoload-dev"，确保主项目也启用了 dev 模式（composer install --dev或COMPOSER_DEV_MODE=1）
生产部署时 path 仓库导致失败怎么办
CI/CD 或生产服务器上不存在本地路径，Composer 找不到 url 就直接报错，不会自动回退到远程仓库。
- 别把
repositories条目提交到 git —— 它只该存在于本地开发环境 - 推荐用 Studio 工具临时覆盖，或通过构建脚本在打包前动态移除
repositories中的 path 条目 - 上线前务必确认
composer.lock里记录的包来源是 Packagist，而不是path类型（可用composer show -a vendor/name查看） - CI 环境若需复现本地依赖，应改用
dist方式：先composer archive打包本地包，再用--repository-url=file://加载
最隐蔽的问题永远是 symlink fallback 成 copy 后还误以为在实时调试；最容易被忽略的细节是本地包 composer.json 里漏了 options 段，或者 IDE 路径映射仍指向 vendor/ 下的副本而非真实源目录。
