根本原因是composer未在主项目composer.json的repositories中配置本地包源，且require声明的包名与本地包composer.json中name字段不一致；需正确配置path源、启用symlink、更新autoload映射并避免路径提交至git。
为什么 composer require vendor/name 报 “Could not find package”
根本原因不是网络或权限问题，而是 Composer 根本没“看见”你的本地目录——它只在主项目 composer.json 的 repositories 数组里找源，require 字段只负责声明“我要哪个包”，不负责“去哪找”。
-
repositories必须写在主项目（即你正在开发的那个项目的）composer.json根级，不能写在本地包自己的composer.json中 -
url必须是相对路径（如"../my-package"），绝对路径在 Windows 上极易静默失败（盘符、反斜杠、空格都会中断） - 本地包目录下必须有合法的
composer.json，且其中name字段（如"acme/utils"）要和require里写的完全一致（大小写敏感、仅允许短横线-，不可用下划线_或大写字母） - 版本约束必须用
dev-main、dev-develop这类分支名，不能写1.0.0——path 源下 Composer 忽略version字段，只认当前 Git HEAD 所在分支
改了本地包代码，为什么主项目里没生效
默认行为是复制（copy），不是链接（symlink）。这意味着你改了 ../my-package/src/Helper.php，vendor/acme/utils/Helper.php 还是旧文件。
- 关键不在主项目配
"options": {"symlink": true}，而在于**本地包自己的composer.json里是否声明了"options": {"symlink": true}**。缺这句，Windows 上即使管理员权限运行终端，也会 fallback；Docker 容器挂载宿主机目录时也常因权限丢失 symlink 能力 - 执行
composer update acme/utils（不是dump-autoload），才会重建 symlink - 验证是否成功：
ls -la vendor/acme/utils（Linux/macOS）应显示箭头指向源目录；Windows 用户用dir vendor\acme\utils看是否为“快捷方式”或JUNCTION类型 - Windows 下必须以管理员身份运行终端，否则 symlink 创建失败且无提示；Docker 场景需加
--cap-add=SYS_ADMIN并确保挂载方式支持 symlink
autoload 不生效，不是 Composer 没加载，而是映射没更新
path 仓库让包“存在”，但类能否被 new 或 use，取决于 autoload 映射是否包含它的真实路径。即使本地包 composer.json 写了 "psr-4": {"Acme": "src/"}，主项目也不会自动同步这个映射。
- 必须手动执行
composer dump-autoload -o，才能刷新类加载映射表 - Xdebug 断点失效？检查 IDE 中配置的路径是否与真实磁盘路径一致（例如 Windows 下
C:\dev\my-pkg和/c/dev/my-pkg在 WSL 中视为不同路径） - 如果本地包用了
classmapautoload，改了文件后也要重新 dump，否则新类不会被识别
生产部署时报错：路径不存在，又不想删配置
Composer 在找不到 path 仓库时会直接报错，而不会自动回退到远程仓库——这是设计使然，不是 bug。它希望你明确知道依赖来源，而不是靠模糊 fallback。
- CI/CD 构建前务必移除
repositories中的 path 条目，否则上线必然失败 - 推荐用环境变量或构建脚本动态生成
composer.json，开发环境保留 path，生产环境跳过 - 更稳妥的做法是用 Studio 工具管理本地覆盖，它不修改
composer.json，所有配置在本地工具层完成，天然规避提交污染和部署风险 - 切记：任何 path 配置都不该进 git，否则团队成员拉代码就可能因路径不一致而集体报错
