答案是name或路径不匹配：name必须大小写、分隔符（仅短横线-）完全一致，路径须指向含composer.json的目录且相对于主项目，末尾不可加/；Windows需管理员权限，Docker需--cap-add=SYS_ADMIN。
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末尾不要加/，"url": "../my-pkg/"会导致静默忽略整个仓库 - Windows 用户避免路径含中文或空格，某些 PHP 版本解析会失败
为什么改了代码没生效？symlink没启用或fallback了
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不生效，不是 Composer 没加载，而是映射没更新
path 仓库让包“存在”，但类能否被new或use，取决于 autoload 映射是否包含它的真实路径。即使本地包composer.json写了"psr-4": {"Acme": "src/"}，主项目也不会自动继承——必须手动触发刷新。
-
composer dump-autoload -o必须在主项目执行，才能把本地包的 autoload 规则合并进vendor/autoload.php - 如果本地包改过
autoload配置（比如新增命名空间），只composer install不够，必须dump-autoload - CI/CD 环境中若禁用 symlink，也要确保
dump-autoload在install之后执行，否则类找不到
上线前不清理 path 配置，部署必然失败
Composer 在解析依赖阶段会验证 path 仓库的路径是否存在。如果生产服务器上不存在该路径，它会直接报错，而不会自动回退到 Packagist 或私有仓库——这是设计使然，不是 bug。
- 上线前必须从主项目
composer.json的repositories中移除所有type: "path"条目 - 对应
require中的版本约束应改为稳定版（如"1.2.0"）或远程分支（如"dev-main"），并提交更新后的composer.lock - CI 流程中建议加校验步骤：
grep -q '"type":"path"' composer.json && exit 1，防止误提交
真正难的不是配通，而是让开发态和部署态在同一个配置里安全共存——symlink 开关、autoload 刷新时机、路径校验逻辑，三者稍有错位，就会在深夜部署时突然报错。
