Composer本地包“Package not found”根本原因是repositories配置未生效：必须置于根composer.json最外层、首项禁用packagist.org、type为"path"、url用相对路径且末尾无/、name与require逐字匹配，否则静默忽略。
本地调试 Composer 包时提示 “Package not found”，不是路径没写对，而是 Composer 根本没去读你的目录——它只在 repositories 配置生效、路径可访问、name 完全匹配的前提下才尝试加载。
为什么 composer show 不显示本地包？
核心问题：Composer 没启用你写的 repositories 配置，或配置被静默忽略。它默认只查 packagist.org，不会主动扫描本地路径。
-
repositories必须放在项目根目录composer.json的**最外层**（和require同级），不能塞进config或extra里 - 第一项必须是
{"packagist.org": false}，否则你的本地源永远排第二，不起作用 -
type字段必须是"path"（不是"vcs"、"git"或留空） -
url值只能是相对路径，如"../my-package"；绝对路径（/home/user/my-package）或带file://前缀的写法会被直接跳过 - 运行
composer config repositories看输出是否包含你配的 path 条目；如果为空或结构异常，说明配置未被识别
路径和 name 字段为何总不匹配？
Composer 不做任何模糊匹配，大小写、连字符、vendor 名、末尾斜杠，错一个就失败。
-
url必须指向**含composer.json的目录**，例如"../packages/my-package"✅，而"../packages"❌（它不会递归找） -
url末尾不能加/："../my-package/"会被静默忽略 - 用
cat ../my-package/composer.json | grep name（Linux/macOS）或findstr name ../my-package/composer.json（Windows）确认输出是"name": "vendor/name"，不是"Vendor/Name"、"vendor_name"或多空格 - 如果
require写的是"vendor/name": "dev-main"，那本地包的分支名必须叫main（不是master或dev）
删了 vendor 还是不重读本地包？
composer clear-cache 不管用，因为它不碰 vendor 目录、不重读 repositories、也不清 Git clone 缓存。
- 先删掉
vendor/vendor/name（不是整个vendor），再跑composer update vendor/name --no-cache - 必须手动清 Composer 的 Git cache：
rm -rf ~/.composer/cache/vcs/*（Linux/macOS）或对应 Windows 路径（如%APPDATA%Composercache cs*） - 加
-vvv运行，日志里必须出现Reading ./../my-package/composer.json，而不是Using version x.x.x from cache - 如果仍走缓存，检查是否误启用了全局
repositories配置（composer config -g repositories），它会覆盖项目级配置
类找到了但 Class not found 怎么办？
包已正确 symlink 进 vendor，但自动加载器没更新——这和安装无关，是 autoload 映射没重建。
- 确认
vendor/autoload.php修改时间晚于composer require时间 - 运行
composer dump-autoload；如果新增了测试类或 Factory，得加--dev参数 - 打开
vendor/composer/autoload_psr4.php，搜索你的命名空间前缀，确认映射路径是绝对路径且结尾有反斜杠（如"App\": "src/"✅，"App": "src/"❌） - 线上环境要清 OPCache 或重启 PHP-FPM，仅刷新页面无效
最容易被忽略的是：只要项目 composer.json 里出现 repositories 字段（哪怕只是空数组 []），Composer 就会彻底屏蔽全局镜像配置，所有排查都得基于项目级配置展开——这时候改全局镜像毫无意义。
