本地包 require 失败主因是 name 或路径不匹配：name 必须严格一致（大小写、短横、vendor 名）、url 需指向含 composer.json 的相对路径、Windows 避中文空格、本地包自身需声明 "options": {"symlink": true"}，且须运行 composer dump-autoload -o 更新自动加载。
本地包 require 失败，90% 是 name 或路径不匹配——Composer 不做模糊匹配，大小写、短横线、vendor 名、相对路径，必须逐字一致。
为什么 composer require vendor/name 找不到包？
不是网络问题，也不是镜像失效，而是 path 仓库根本没被 Composer 识别。常见现象：composer show --all 里压根不出现该包名。
-
name字段必须和require中写的完全相同：比如本地包composer.json里写的是"acme/utils"，你就不能在主项目里写"Acme/utils"或"acme_utils" -
url必须指向**含composer.json的目录**，且是相对于主项目composer.json的路径，例如"../my-pkg"；末尾加/（如"../my-pkg/"）会导致静默忽略整个仓库 - Windows 用户要避开路径中含中文或空格，某些 PHP 版本解析会失败
- 确认本地包根目录下
composer.json语法合法：无尾逗号、全双引号、JSON 格式有效（可用php -l ../my-pkg/composer.json验证）
改了本地代码，vendor/ 里还是旧的？
这是最隐蔽的坑：symlink 没真正生效，Composer fallback 到了 copy 模式。
- 关键不在主项目配置
"symlink": true，而在于**本地包自己的composer.json是否声明了"options": {"symlink": true}** - Windows 下必须以管理员身份运行终端，否则创建 symlink 失败且无提示
- Docker 场景需加
--cap-add=SYS_ADMIN，并确保挂载方式支持 symlink（如-v $(pwd)/my-pkg:/app/my-pkg） - 验证是否真用了 symlink：
ls -la vendor/vendor/name（Linux/macOS）或dir vendor endor ame（Windows），看到箭头或JUNCTION才算成功；若显示普通文件夹，说明 fallback 成 copy 了
autoload 不生效，类找不到怎么办？
包“存在”不等于类能被 use 或 new，autoload 映射必须覆盖真实路径。
- 即使本地包
composer.json写了"psr-4": {"Acme\": "src/"}，主项目也不会自动继承这个映射 - 必须手动触发 autoload 更新：
composer dump-autoload -o（注意：不是install或update） - Xdebug 断点不命中？检查 IDE 中设置的路径是否与磁盘真实路径完全一致（尤其 Docker 或 WSL 环境下，路径映射错位很常见）
真正难调的从来不是报错信息本身，而是 symlink 是否启用、autoload 是否重载、路径是否相对于主项目——这三处一旦出错，现象都像“代码没更新”，但原因完全不同。动手前先跑一遍 ls -la vendor/... 和 composer dump-autoload -o，比反复 install 有用十倍。
