“Could not find package”主因是本地包name字段与require语句不完全一致，须逐字比对（大小写、短横线/下划线、空格均敏感）；repositories必须置于composer.json根级，path类型仓库url需相对主项目且末尾无斜杠，本地包composer.json须合法且含name/version。
Composer报“Could not find package”但本地包明明存在
这90%不是路径没找到，而是name字段和require语句不完全一致。Composer不做大小写折叠、不接受下划线替代短横线、不忽略空格——逐字比对才是关键。
检查点清单：
-
require里写的包名（如acme/utils）必须和本地包composer.json中"name": "acme/utils"**完全相同**；Acme/utils、acme_utils、acme-utils全都不行 -
url值是相对于主项目composer.json的路径，不是 shell 当前目录；写成"../my-pkg"是对的，"./packages/my-pkg"也行，但"file:///home/user/my-pkg"或"C:\dev\my-pkg"会静默失效 - 路径末尾不能加
/，"url": "../my-pkg/"会导致整个仓库被跳过，不报错也不提示 - 本地包根目录下必须有合法
composer.json：无尾逗号、全双引号、JSON 语法有效；缺name或version（且主项目没设"minimum-stability": "dev"）也会被跳过
装上了但改代码不生效，Class not found 或逻辑没变
最隐蔽的问题是 symlink 没真正建立，Composer fallback 到了 copy 模式——你改的是源码，vendor 里还是旧副本。
验证与修复步骤：
- Linux/macOS 执行：
ls -la vendor/acme/utils，看到箭头->才是 symlink；Windows 执行：dir vendor\acme\utils，看到JUNCTION才对 - 若显示为普通文件夹，说明 fallback 成 copy，立刻检查**本地包自己的
composer.json**是否含"options": {"symlink": true}——这个配置不在主项目，而在被引用的本地包里 - Windows 用户必须以管理员身份运行终端；Docker 需启动时加
--cap-add=SYS_ADMIN，否则 symlink 创建失败且无提示 - autoload 不更新？执行
composer dump-autoload（开发阶段不用-o），因为 path 仓库不会自动触发 autoload 重生成
为什么 composer show --all 里看不到本地包
说明 Composer 根本没加载那个 path 仓库——不是包有问题，是仓库声明位置或格式错了。
常见配置陷阱：
-
repositories必须写在主项目composer.json的**根级**，不能塞进require、config或任何嵌套字段里 - 必须是数组：
"repositories": [{ "type": "path", "url": "./packages/my-utils" }]，写成对象{"type": "...", "url": "..."}会静默忽略 -
type必须是"path"，不是"package"或"vcs"；拼错一个字母就失效 - 路径指向的目录里如果连
composer.json都没有，Composer 会跳过该仓库，不报错也不警告
Windows 下 symlink 失败、Docker 中路径错乱
Windows 和 Docker 对符号链接的支持是“有条件”的，不是开箱即用。
具体应对方式：
- Windows：避免路径含中文、空格或长路径（尤其在
%USERPROFILE%下）；某些 PHP 版本解析composer.json时会因路径编码异常直接跳过仓库 - Docker：挂载宿主机目录时，确保使用
docker run -v $(pwd)/packages:/app/packages这类显式挂载，而非仅靠COPY；容器内需启用SYS_ADMIN能力，且基础镜像支持 symlink（Alpine 默认不支持，推荐用php:apache或php:fpm官方镜像） - IDE 调试断点不命中？Xdebug 路径映射依赖真实磁盘路径；PhpStorm 中需确认
Settings > PHP > Servers里的路径映射与容器内实际路径一致，否则断点永远不触发
真正卡住人的，往往不是“怎么配”，而是“配完以为好了，其实 symlink 没建、autoload 没刷、IDE 路径没对齐”。每一步都得亲手验证，不能靠composer install成功就默认万事大吉。
