根本原因是本地包 composer.json 缺少 "options": {"symlink": true}，导致 composer 回退到 copy 模式，vendor 中为普通目录而非符号链接；同时 autoload 映射未更新，需手动执行 composer dump-autoload -o。
为什么改了本地包代码，vendor里还是旧的
根本原因是 symlink 没真正生效，Composer fallback 到了 copy 模式——你看到的 vendor/vendor/name 是个普通文件夹，不是符号链接。这和主项目 composer.json 里配没配 "symlink": true 无关，关键在**本地包自己的 composer.json 是否声明了 "options": {"symlink": true}**。
- 缺这句，Windows 上即使管理员权限运行终端，也会静默 fallback
- Docker 容器挂载宿主机目录时，
symlink常因权限丢失而失效 - 验证方式：Linux/macOS 执行
ls -la vendor/vendor/name，看到箭头才是 symlink；Windows 用dir vendor\vendor\name，看到JUNCTION或SYMLINKD才对 - 如果显示为普通目录，立刻检查本地包根目录下的
composer.json是否漏了options段
path 仓库 require 成功但类找不到
不是 Composer 没加载包，而是 autoload 映射没更新到真实路径。即使本地包 composer.json 写了 "psr-4": {"Acme": "src/"}，主项目也不会自动继承这个映射。
- 必须手动执行
composer dump-autoload -o，让 Composer 重新扫描并生成优化后的 autoload map - 注意：仅
composer install或update不会触发 autoload 更新，除非你删了vendor/autoload.php - Xdebug 断点不命中？确认 IDE 里打开的文件路径和磁盘上真实路径完全一致（比如 Windows 下
C:\work\my-pkg\src\X.php≠c:\work\my-pkg\src\X.php）
require 失败但 composer show --all 里压根不显示包名
90% 是 name 或路径不匹配。Composer 不模糊匹配，大小写、分隔符、vendor 名必须逐字相同。
-
name字段值必须和require中写的完全一致："acme/utils"≠"Acme/utils"≠"acme_utils" - 路径是相对于主项目
composer.json的位置，例如"../my-pkg"，不能是./my-pkg或绝对路径 - 路径末尾不能加
/："url": "../my-pkg/"会导致整个仓库被静默忽略 - Windows 用户避免路径含中文或空格，某些 PHP 版本解析会失败
- 确认本地包根目录下有合法
composer.json：无尾逗号、全双引号、JSON 语法有效
生产环境 path 仓库根本不能用
path 类型仓库只适合开发调试，CI/CD 和生产部署中必须禁用。它依赖本地文件系统路径，在容器、远程服务器、多节点部署场景下完全不可靠。
-
composer install在生产机上遇到 path 仓库会直接报错或跳过，不会 fallback - Docker 构建时若未挂载对应路径，
composer install会卡在 “Could not find package” - 正确做法：开发阶段用 path，上线前用
composer remove vendor/name+composer require vendor/name:^x.y切回正式发布版 - 私有 Git 仓库 +
type: git是更安全的替代方案，支持 tag、branch、commit hash 精确控制
vendor/ 里是不是真链接，再看 vendor/autoload.php 里有没有映射到你改的那个文件路径。
