config.vendor-dir 必须为相对路径且不能跨出项目根目录，如"libs"或"src/vendor"；path仓库url需以./或../开头并含合法composer.json；启用symlink才能使本地修改实时生效。
composer.json 中 config.vendor-dir 必须写相对路径
vendor 目录只能移到项目内部子目录，不能跨出项目根目录。比如项目在 /var/www/myapp，你可以设成 "vendor-dir": "libs" 或 "vendor-dir": "src/vendor"，但 "vendor-dir": "../shared/vendor" 会静默失败——Composer 在解析依赖、生成 autoload、执行脚本时，全部硬编码了 “vendor 在当前项目内” 这一前提。
常见错误现象：
-
COMPOSER_VENDOR_DIR=../vendor composer install表面成功，但require 'vendor/autoload.php'报错找不到文件 -
composer dump-autoload提示Class not found in PSR-4 mapping - PHPUnit 或 PHPStan 的 bin 命令执行失败，因为它们的 autoloader 是按相对
vendor/构建的
正确做法是直接改项目级 composer.json：
{
"config": {
"vendor-dir": "libs"
}
}
然后运行 composer install。注意：IDE（如 PhpStorm）可能缓存旧路径，需手动刷新索引或重启。
path 类型仓库的 url 必须是相对路径且含合法 composer.json
想把 modules/payment 当作独立包引入？repositories 里的 url 必须以 ./ 或 ../ 开头，且目标目录下必须存在完整、合法的 composer.json，并且该目录已提交至少一个 Git commit。
支持通配符，例如："url": "modules/*"，Composer 会扫描所有匹配子目录；但不支持 "url": "/home/user/pkg"、"url": "file:///tmp/pkg" 或 "url": "my-package"（缺上级路径符号）。
本地包的 composer.json 还必须满足三个条件：
-
name字段（如"myapp/payment"）要和主项目require中声明的完全一致（大小写敏感） - 必须有
autoload配置（如 PSR-4 映射），否则类加载失败 - 版本约束要用
dev-main这类分支名，不能写1.0.0——path 源忽略version字段
启用 symlink 才能让本地修改实时生效
默认情况下，Composer 对 path 仓库采用复制（copy）模式，改了 modules/payment/src/Helper.php，vendor/myapp/payment/src/Helper.php 不会自动更新。
必须显式启用符号链接：
- 在主项目
composer.json的对应repositories条目里加："options": {"symlink": true} - 或在本地包自己的
composer.json里加同样字段 - 然后运行
composer update myapp/payment（不是dump-autoload）
验证是否成功：
- Linux/macOS：运行
ls -la vendor/myapp/payment，应看到箭头指向源目录 - Windows：运行
dir vendor\myapp\payment，类型应为“快捷方式”，且需开启开发者模式或管理员权限才能创建 symlink
bin-dir 和 cache-dir 的路径逻辑完全不同
bin-dir 是项目级配置，可安全设为 "bin-dir": "bin"，Composer 会自动创建目录并链接命令（Windows 下生成 .bat 文件）。但 cache-dir 是全局配置项，写在项目 composer.json 里会被忽略。
改缓存路径唯一可靠方式是：
- 运行
composer config --global cache-dir /data/composer-cache - 确保路径存在且当前用户有读写权限
- 不要用
~，Composer 不解析 shell 符号，必须写绝对路径
而 vendor-dir 虽然也能通过 COMPOSER_HOME/config.json 全局设置，但那会导致所有项目共用一个 vendor，实际协作中极易引发冲突——项目级 config.vendor-dir 才是多数场景下真正可控、可复现的选择。
