Composer path仓库生效需同时满足：type为"path"、url是本地绝对或相对路径（以./或../开头）、路径下有含合法name字段的composer.json及.git目录；否则静默忽略。
path仓库必须是完整Git项目（含.git目录）
Composer的path类型仓库不是简单指向一个文件夹，它要求目标路径下存在有效的.git目录，且该目录能被git rev-parse --show-toplevel识别为工作区根。如果只是把源码拷贝过去而没带.git，Composer会报错：Source path ... does not appear to be a VCS repository。
实操建议：
- 用
git clone完整克隆依赖项目到目标路径，不要只复制src/或vendor/子目录 - 若依赖项目本身未初始化Git，需在该目录下运行
git init && git add . && git commit -m "init" - 路径可使用相对路径（如
../my-package）或绝对路径（如/Users/me/dev/my-package），但相对路径以composer.json所在目录为基准
require和repositories配置必须同时存在
仅在repositories里加path条目不会生效——Composer仍会去Packagist拉取线上版本。必须同时在require中声明包名和版本，并确保该包名与目标项目composer.json中的name字段完全一致（包括命名空间，如acme/utils）。
典型配置示例：
{
"repositories": [
{
"type": "path",
"url": "../my-utils"
}
],
"require": {
"acme/utils": "dev-main"
}
}
注意点：
-
dev-main这类开发分支名必须与目标项目Git分支名严格匹配；若目标项目只有master分支，这里就得写dev-master - 如果目标项目
composer.json里没设name，Composer会拒绝识别，报错：Package acme/utils cannot be found in any version control system - 执行
composer update acme/utils比全量update更安全，避免意外刷新其他依赖
符号链接行为取决于Composer版本和平台
Composer 2.0+ 默认对path仓库创建符号链接（symlink），而非复制文件。这带来便利也埋了坑：Windows上非管理员权限可能无法创建symlink；某些IDE或部署脚本不跟踪symlink内容；修改上游代码后，下游composer install不会自动更新（因为没触发重安装逻辑）。
应对方式：
- 确认是否启用symlink：查看
vendor/acme/utils是否为指向../my-utils的链接（macOS/Linux用ls -l，Windows用dir） - 强制复制而非链接：在
config中加"preferred-install": {"acme/utils": "dist"}，或全局设COMPOSER_PREFER_DIST=1 - 开发时主动同步：改完
../my-utils后，在主项目运行composer update acme/utils --no-install再composer install，确保引用最新快照
autoload映射冲突会导致类找不到
即使path加载成功，如果主项目和依赖项目的autoload规则有重叠（比如都用了"psr-4": {"App\": "src/"}），PHP可能从错误路径加载类，报Class not found。
检查重点：
- 依赖项目
composer.json中的autoload应明确限定自身命名空间，例如"psr-4": {"Acme\Utils\": "src/"}，而不是宽泛的"App\" - 主项目执行
composer dump-autoload -o后，检查vendor/composer/autoload_psr4.php里是否同时存在两个同前缀的映射 - 临时调试可用
composer show -s acme/utils确认其实际加载路径是否为你预期的../my-utils
跨目录path依赖本质是让Composer把本地目录“伪装”成一个可版本化仓库，所有约束都围绕这个前提展开。最容易卡住的地方不是配置写法，而是.git是否存在、name是否匹配、autoload是否打架——这三处任一出问题，都会表现为“明明配了却走线上包”或“类存在但加载失败”。
