根本原因是 symlink 未生效，导致运行时加载 vendor 中的静态副本而非源码；验证需用 readlink 或 dir 检查链接，且本地包 composer.json 必须配置 "options": {"symlink": true}。
为什么改了本地包代码，主项目里没反应
大概率是 symlink 没真正建立，Composer fallback 到了 copy 模式。你看到 vendor/ 下有文件，但那只是副本，改本地源码根本不会同步。
关键不在主项目 composer.json 里配 "symlink": true，而在于**本地包自己的 composer.json 中必须声明 "options": {"symlink": true}**。缺这句，Windows 上即使管理员权限运行终端，也会静默 fallback；Docker 容器挂载宿主机目录时也常因权限丢失 symlink 能力。
- Linux/macOS 验证：运行
readlink vendor/vendor/name，输出应为你的本地路径（如../../my-pkg） - Windows 验证：运行
dir vendor endor ame，看到JUNCTION或箭头才是成功；若显示普通文件夹，说明 fallback 成 copy - Windows 用户务必以管理员身份运行终端，否则 symlink 创建失败且无提示
- Docker 场景需在
docker run时加--cap-add=SYS_ADMIN，并确认挂载方式支持符号链接
Class not found 是 autoload 没加载，不是包没装上
path 仓库让包“存在”，但类能否被 new 或 use，取决于 autoload 映射是否包含它的真实路径。即使本地包 composer.json 写了 "psr-4": {"Acme": "src/"}，主项目也不会自动继承——必须手动触发更新。
- 确认本地包的
composer.json中autoload或autoload-dev正确声明了映射，例如："psr-4": {"MyPackage\": "src/"}（注意双反斜杠和路径一致性） - 测试类在
tests/下？autoload-dev的 PSR-4 映射末尾必须带反斜杠："MyPackage\Tests\": "tests/"，少一个就断掉 - 无命名空间的辅助文件（如
tests/bootstrap.php）不能塞进 PSR-4，得用autoload-dev.files单独引入 - 改完 autoload 配置后，必须手动执行
composer dump-autoload（开发阶段不用加-o），否则新映射不会写入vendor/composer/autoload_static.php
require 报 “Could not find package” 的真实原因
这不是网络或缓存问题，90% 是 repositories 根本没被 Composer 读到，或者 name / 路径不匹配。Composer 不会模糊匹配，大小写、分隔符（只能用短横线 -）、vendor 名全部敏感。
-
repositories必须写在项目composer.json的根级（和require同级），不能嵌在extra或require里 -
url必须以./或../开头，不解析~、$HOME、绝对路径或file://协议 - 路径指向的是**含
composer.json的目录**，不是文件，且必须是相对于主项目composer.json的位置（如"../my-pkg"），末尾不可加/ - 本地包
composer.json中的name字段必须和require中写的逐字相同，例如"acme/utils"≠"Acme/utils"≠"acme_utils" - Windows 用户避免路径含中文或空格，某些 PHP 版本解析会失败
怎么确认 path 仓库真生效了
别只看 vendor/ 目录有没有文件，得验证底层链接和运行时加载是否通。
- 执行
composer show vendor/name --path，输出应为vendor/vendor/name的绝对路径 - 执行
php -r "echo class_exists('MyPackage\Calculator') ? 'ok' : 'fail';"，输出ok才说明生产 autoload 生效 - 执行
php -r "echo file_exists('vendor/vendor/name/src/Calculator.php') ? 'file exists' : 'not found';"，确认物理文件可访问 - 如果 Xdebug 断点不触发，检查 IDE 中配置的路径是否与真实磁盘路径一致（尤其 Docker 或 WSL 场景下路径映射容易错位）
路径对齐、name 对齐、symlink 启用、autoload 更新——这四点漏掉任意一个，调试就会卡在“看似装上了，实则没生效”的状态。最隐蔽的是 symlink fallback，它不报错、不警告，只默默复制一份旧代码进去。
