Composer path仓库require失败主因是name或路径不匹配：name须逐字一致（大小写、短横线）、路径须为含composer.json的目录且相对主项目，常见错误包括JSON无效、尾斜杠、中文路径、symlink未启用或权限不足。
path仓库require失败：90%是name或路径不匹配
Composer不会模糊匹配包名或路径，name字段必须和require中写的字符串逐字一致：大小写、分隔符（只允许短横线-，不能用_或大写字母）、vendor名全部对齐。路径也一样——url指向的是**含composer.json的目录**，不是文件，且必须是相对于主项目composer.json的位置（如"../my-pkg"），不能是 shell 当前工作目录下的相对路径。
常见错误现象：Could not find package vendor/name，但composer show --all里根本没出现该包名。
- 检查本地包根目录下是否存在合法
composer.json（无尾逗号、全双引号、JSON语法有效） - 确认
name字段值与require中字符串完全相同，例如"acme/utils"≠"Acme/utils" - 路径末尾不要加
/，"url": "../my-pkg/"会导致静默忽略整个仓库 - Windows 用户避免路径含中文或空格，某些 PHP 版本解析会失败
symlink没生效：改了代码却还是旧副本
path 类型仓库默认尝试创建符号链接，但失败时会静默回退到复制（copy），结果你改本地源码，vendor/里还是旧副本——这是最隐蔽的调试陷阱。
关键不在主项目配"symlink": true，而在于**本地包自己的composer.json里是否声明了"options": {"symlink": true}**。缺这句，Windows 上即使管理员权限运行终端，也会 fallback；Docker 容器挂载宿主机目录时也常因权限丢失 symlink 能力。
验证是否真用了 symlink：ls -la vendor/vendor/name（Linux/macOS）或dir vendor\vendor\name（Windows），看到箭头或JUNCTION才是成功。若显示为普通文件夹，说明 fallback 成 copy，立刻检查本地包composer.json是否漏了options段。
- Windows 下必须以管理员身份运行终端，否则 symlink 创建失败且无提示
- Docker 场景需在
docker run时加--cap-add=SYS_ADMIN并确保挂载方式支持 symlink
autoload 不更新：类能被 require 但 new 不出来
path 仓库让包“存在”，但类能否被new或use，取决于 autoload 映射是否包含它的真实路径。即使本地包composer.json写了"psr-4": {"Acme": "src/"}，主项目也不会自动加载——因为 autoload 映射是在composer install或update时生成的，不随 path 仓库内容变化实时刷新。
- 修改本地包后，必须手动运行
composer dump-autoload -o，否则新类不会进 autoload map - 如果改了命名空间或目录结构，仅
dump-autoload不够，要先composer update vendor/name触发重映射 - IDE 中类跳转失效？检查 IDE 是否识别了 symlink 目标路径，而非
vendor/里的副本
部署环境特别注意：Docker 和 Windows 权限链断裂
在 Docker 或 Windows 部署中，path 仓库极易因权限或路径解析中断而 fallback 到 copy 模式，导致热更新失效、类加载错乱、甚至 CI 构建通过但运行时报Class not found。
根本原因不是 Composer 配置错，而是底层系统能力缺失：Docker 默认不支持 symlink，Windows UAC 限制符号链接创建，且realpath()在中文路径下可能直接返回 false。
- Docker 运行容器时必须加
--cap-add=SYS_ADMIN，且挂载方式要用bind mount而非copy或volume - Windows 部署请把项目移出 OneDrive / 腾讯微云等同步文件夹，它们会拦截 symlink 创建
- CI 流水线中避免使用
composer install --no-dev后又手动改本地包——dev 依赖缺失可能导致 autoload 生成不完整
