根本原因是name、path、version、autoload四者未对齐；包名须严格小写且含短横线，path需为相对路径且type为path，版本须匹配dev-分支名，autoload必须声明并执行dump-autoload。
本地包配置后 composer require 报 “Could not find package” 或装上了却 Class not found，根本原因不是 Composer 坏了，而是 name、path、version、autoload 四者中至少有一处没对齐——它不报错，只静默跳过。
本地包 name 和 require 必须逐字一致
Composer 对包名大小写、分隔符完全敏感，name 字段里写的是 "acme/utils"，你就必须执行 composer require acme/utils:dev-main。写成 Acme/Utils、acme_utils、acmeutils 全部失败，且 composer show --all 根本不会列出这个包。
-
name只能含小写字母、短横线-，不能有下划线_、大写字母、点号. - 检查本地包根目录下的
composer.json：确认name存在、语法合法（无尾逗号、全双引号）、无不可见空格 - 路径中含中文或空格（尤其 Windows）会导致解析失败，建议重命名为纯英文无空格目录
repositories 配置位置和格式不能错
必须写在项目根目录 composer.json 的最外层 repositories 数组里，不是嵌套在 require、config 或其他字段下；type 必须是 "path"，url 是相对于该 composer.json 的路径。
- 正确写法：
"repositories": [{ "type": "path", "url": "./packages/my-utils" }] -
url末尾不能加/，"./packages/my-utils/"会被完全忽略 - 不能用
file://前缀，也不能用绝对路径（如C:/xxx或/home/user/xxx） - 本地包目录必须包含合法的
composer.json，否则该仓库被跳过，不提示也不报错
版本约束必须匹配 dev- 分支名
path 类型仓库基本忽略本地包 composer.json 中的 version 字段，而是按 Git 分支名推断版本。如果你本地包默认分支是 main，就必须用 dev-main；是 develop，就得写 dev-develop。
- 本地包目录需已运行
git init并至少有一个 commit，否则 Composer 拒绝加载 - 若未设置
"minimum-stability": "dev"，又没在require中显式写dev-main，该包会被稳定性策略过滤掉 - 不要用
"*"或"^1.0"，path类型不支持语义化版本约束
autoload 映射失效比没装更难排查
包“装进来了”不代表类能用。90% 的 Class not found 问题出在 autoload 配置或未刷新映射上，和 Composer 安装流程无关。
- 本地包自己的
composer.json必须声明合法的autoload，例如："psr-4": {"Acme\Utils\": "src/"}（注意命名空间结尾双反斜杠） - 修改后必须手动运行
composer dump-autoload，否则新命名空间不会注册 - 如果包提供 Laravel Service Provider，仍需手动在
config/app.php中注册 —— Composer 不处理这部分 - Windows 下符号链接行为异常，有时 fallback 为复制，改了代码却看不到效果，建议用
ls -la vendor/acme/utils确认是否为 symlink
最常被忽略的一点：所有检查都通过后，仍要确认本地包目录下 src/（或你声明的 autoload 路径）真实存在，且类文件路径与命名空间严格对应——少一个目录、错一个大小写、多一个反斜杠，都会让自动加载器彻底失联。
