必须配置path仓库并用""约束：检查repositories中type为path且url是相对路径、本地包composer.json的name与require完全一致、require写为"my-vendor/pkg": ""，否则Composer只查Packagist。
composer require my-vendor/pkg:1.2.3 报 “Could not find package”
这是最典型的本地包误用场景：Composer 默认只查远程源，1.2.3 被当成已发布的稳定版本去 Packagist 搜索，根本不会看你的本地文件夹。
必须走 path 类型仓库 + "*" 约束，否则必失败。检查三件事：
-
composer.json顶部repositories块是否配置了"type": "path"，且url是相对路径（如"./packages/my-pkg"），不能带尾部斜杠 - 本地包目录下是否存在合法
composer.json，其中name字段（如"my-vendor/pkg"）必须和主项目require中的完全一致（大小写敏感） -
require里写的必须是"my-vendor/pkg": "*"，写"dev-main"或"1.2.3"都会触发错误或静默忽略
运行 composer install 后 vendor/ 下没生成本地包
不是安装失败，而是 Composer 根本没把它纳入依赖图——常见于 composer.lock 未同步更新。
composer install 只按 composer.lock 还原，不会读取 composer.json 新增的 require。必须先让变更落地：
- 删掉
composer.lock（或至少确认它已提交 Git），再跑composer update my-vendor/pkg，而不是install - 执行
composer config repositories，确认输出里有你配的path条目；若无，说明配置未生效 - 进本地包目录执行
composer validate，确保语法合法、version字段存在——path仓库只认这个字段，不解析语义化版本
vendor/my-vendor/pkg 是普通目录，不是符号链接
预期是软链接指向本地路径，结果却是拷贝出来的独立副本，说明 path 仓库虽注册成功，但 Composer 没启用“挂载模式”。
原因通常是 require 的约束值不对，或本地包 composer.json 缺少 version。验证方式：
- 运行
composer show my-vendor/pkg，看输出的 version 是否和本地包composer.json里的一致；不一致说明被缓存覆盖，加-vvv查日志定位来源 - 检查主项目
composer.json的require是否用了"*"；若用了"dev-main"，会报Invalid version string - 确认没有在
config里设"preferred-install": "dist"—— 这会让 Composer 强制走 ZIP 下载，绕过path逻辑
本地包改了代码，但主项目 autoload 不生效
autoload 映射由 composer dump-autoload 生成，而 path 仓库的改动不会自动触发重生成。
尤其当本地包 composer.json 的 autoload 字段（如 "psr-4"）有变更时，必须手动刷新：
- 在主项目根目录运行
composer dump-autoload -o（优化模式）或composer dump-autoload（开发模式） - 如果改的是本地包的类名或命名空间，还要确认
vendor/composer/autoload_psr4.php里对应映射已更新 - CI/CD 环境中，别依赖
composer install自动处理 autoload——它只在首次安装或 lock 变更时生成，后续本地修改必须显式调用dump-autoload
本地包调试真正的难点不在配置，而在信任链断裂：Composer 对 path 仓库的 version 字段照单全收，但一旦你忘记改本地包的 composer.json 里的 version，或者误删了 composer.lock 又没跑 update，整个链路就静默失效。每次怀疑失败，优先跑 composer show 和 composer config repositories，比删 vendor 重装快十倍。
