Composer path仓库require失败90%因name或路径不匹配：name须大小写、分隔符逐字一致，url须为相对路径且指向含合法composer.json的目录，末尾不可加/。
path仓库require失败：name和路径必须逐字匹配
Composer找不到本地包，90% 是因为 name 字段或 url 路径写错了——它不忽略大小写、不兼容下划线、不接受尾部斜杠，也不做模糊匹配。
常见现象：Could not find package vendor/name，但 composer show --all 里压根没这个包名。
-
name必须和require中写的完全一致：比如"acme/utils"≠"Acme/utils"≠"acme_utils" -
url指向的是**含composer.json的目录**，且是相对于主项目composer.json的路径（如"../my-pkg"），不能是 shell 当前位置的相对路径 - Windows 下路径避免含中文、空格；末尾加
/（如"../my-pkg/"）会导致整个仓库被静默忽略 - 用
ls -la ../my-pkg（Linux/macOS）或dir ..my-pkg（Windows）确认该目录下真有合法composer.json（无尾逗号、全双引号、JSON 有效）
symlink没生效：本地改代码却没更新到vendor
你改了本地包源码，vendor/ 里还是旧副本？不是 Composer 没运行，而是 symlink 创建失败后 fallback 成了 copy，且全程无提示。
关键不在主项目配置，而在**本地包自己的 composer.json 是否声明了 "options": {"symlink": true}**。
- 缺这句，Windows 上即使管理员权限运行终端，也会 fallback；Docker 容器挂载宿主机目录时也常因权限丢失 symlink 能力
- 验证是否真用了 symlink：
ls -la vendor/vendor/name（Linux/macOS）看到箭头，或dir vendor endor ame（Windows）看到JUNCTION才算成功 - 若显示为普通文件夹，立刻检查本地包根目录下的
composer.json是否漏了options段 - Windows 用户必须以管理员身份运行终端；Docker 需加
--cap-add=SYS_ADMIN并确保挂载方式支持 symlink
autoload不生效：类能 require 但 new 不出来
包已成功拉进 vendor/，composer show 也能看到，但 new AcmeSomeClass() 报错——这不是依赖没装，而是 autoloader 没映射到你改后的源码路径。
- 执行
composer dump-autoload -o强制刷新自动加载映射（尤其改过本地包composer.json的autoload段后） - Xdebug 断点失效？检查 IDE 里打开的文件路径是否和磁盘真实路径一致（比如 Windows 下
C:devmy-pkg和c:devmy-pkg大小写不一致会断点失败） - 确认本地包
composer.json的autoload配置指向的是它自己目录内的相对路径（如"psr-4": {"Acme\": "src/"}），不是绝对路径或错误子目录
权限与环境陷阱：Windows 和 Docker 特别容易踩
报 Permission denied 或直接静默失败，往往和系统级限制有关，不是 Composer 配置问题。
- Windows 下杀软（尤其是 Windows Defender 实时防护）会拦截
.bat生成或 symlink 创建；临时禁用实时防护再试，或改用 Git Bash - Docker 场景中，若用
-v挂载本地 path 仓库，容器内 PHP 进程需有读取宿主机文件权限；推荐加--user $(id -u):$(id -g)启动容器 - CI 流水线里 path 仓库几乎必然失败——因为 CI 环境没有你的本地目录结构；path 类型只适用于本机开发，上线前必须换为 packagist 正式发布
路径依赖本质是“让 Composer 当本地文件系统为包源”，它绕过了网络和版本解析，但也把所有路径、权限、符号链接的底层细节全暴露了出来。最容易被忽略的，是以为配对了 name 和 url 就万事大吉，却没检查本地包自己是否启用了 symlink、autoload 是否刷新、IDE 路径是否大小写敏感。
