vendor目录没更新的根本原因是symlink未生效，导致Composer静默fallback到copy模式；需检查本地包composer.json是否含"options": {"symlink": true}，并用ls -la或dir验证链接是否成功。
挂载 Composer path 仓库时 vendor 目录没更新？检查 symlink 是否生效
path 类型仓库（"type": "path"）默认尝试创建符号链接，但失败时会静默 fallback 到复制（copy）——你改了本地包代码，vendor/ 里还是旧副本，这是最常被忽略的根源。
关键不在主项目 composer.json 配 "symlink": true，而在于本地包自己的 composer.json 必须声明：
{
"name": "acme/utils",
"type": "path",
"autoload": { "psr-4": {"Acme\": "src/"} },
"options": {
"symlink": true
}
}
验证是否真用了 symlink：
- Linux/macOS：
ls -la vendor/acme/utils—— 看到箭头（→）才是成功 - Windows：
dir vendorcmeutils—— 看到JUNCTION或SYMLINKD才是 symlink；普通文件夹= fallback 成 copy
Docker 中 path 仓库挂载失败：权限与挂载模式必须匹配
Docker 默认不支持在容器内创建 symlink，尤其当宿主机目录通过 volumes 挂载进来时，symlink 能力常因权限丢失而失效。
必须同时满足以下三点：
- 运行容器时加
--cap-add=SYS_ADMIN（Linux）或确保 Windows Docker Desktop 启用 WSL2 并以管理员身份启动终端 -
docker-compose.yml 中挂载方式不能用
:cached或:delegated（它们会破坏 symlink 语义），应显式用:rw或省略模式（默认 rw） - 挂载路径必须指向含合法
composer.json的目录，且路径相对于主项目composer.json的位置——例如主项目在/app，本地包在/app/../my-pkg，则"url": "../my-pkg"，末尾不能带/
为什么 composer install 不报错却没拉进 path 包？name 字段大小写和分隔符必须完全一致
Composer 不做模糊匹配。90% 的 “Could not find package” 是因为 require 中写的包名和本地包 composer.json 里的 "name" 字段不逐字相等。
确认以下细节：
-
"name": "acme/utils"≠"acme/utils"（多空格、换行、BOM 头都会导致失败） - 只允许短横线
-，不允许下划线_或大写字母（"Acme/Utils"无效） - 路径中不能含中文、空格或特殊字符（Windows 尤其敏感）
- 本地包根目录下必须存在语法合法的
composer.json（无尾逗号、全双引号、JSON 格式正确）
autoload 不生效？别只信 composer dump-autoload -o
symlink 建立成功 ≠ 类能被自动加载。autoload 映射仍需真实路径参与生成。
如果改了本地包的 src/ 结构或命名空间，必须在主项目根目录手动执行：
composer dump-autoload -o
注意：
- 不要在本地包目录里执行该命令——它只影响当前项目的 autoload，不是 symlink 目标
- IDE 断点不命中？检查 IDE 设置中的“路径映射”是否把
vendor/acme/utils正确指向宿主机上的真实路径（如/Users/me/my-pkg），否则 Xdebug 无法关联源码
实际操作中最容易卡住的，不是配置写法，而是 symlink 是否真正建立、autoload 是否重新生成、以及 IDE 路径映射是否同步——三者缺一不可。
