Class not found 的根本原因是 autoload 配置错误、未执行 composer dump-autoload 或命名空间/路径不匹配；path 仓库需在根 composer.json 的 repositories 中显式声明，本地包 require 必须用 dev-main 等分支名，且 PSR-4 映射须严格对应文件结构并正确转义。
本地包装进 vendor 但 Class not found，不是 Composer 没加载，而是 autoload 配置没对上、没 dump、或命名空间拼错了——path 仓库本身只管“把包软链进来”，自动加载完全由你写的 autoload 和 composer dump-autoload 控制。
path 仓库配置必须写在项目根 composer.json 的 repositories 数组里
Composer 不会扫描子目录或读取包自己的 composer.json 来发现 path 源。它只认项目根目录下 composer.json 中顶层 repositories 字段的声明。
-
repositories必须是数组，哪怕只有一个源也要写成[{ "type": "path", "url": "./packages/my-utils" }] -
url是相对于项目composer.json的路径，不能带file://，不能用~/或环境变量，../my-pkg可以，/home/user/pkg在 CI 中大概率静默失败 - 本地包目录下必须有合法的
composer.json，且含name（如"mycompany/utils"）和至少一个version（推荐"dev-main"） - 如果本地包没
git init过、或没任何 commit，Composer 会跳过该仓库，不报错也不提示
require 时必须用 dev-main 等分支名，不能写 * 或 ^1.0
path 类型仓库下的包，Composer 不解析 version 字段，而是直接读取本地 Git HEAD 所在分支名，并强制要求你在 require 中显式写成 "dev-main"、"dev-develop" 等形式。
- 执行
composer require mycompany/utils:dev-main，不是:*，也不是:1.0.0 - 若本地包默认分支是
develop，就得同步改require为"dev-develop" - 装完后检查
vendor/mycompany/utils：Linux/macOS 下ls -l应显示-> ../packages/my-utils；如果是普通文件夹，说明 path 仓库根本没生效 - 更新单个包用
composer update mycompany/utils，避免全量 update 触发其他依赖重装
autoload 配置写错一个字符就 Class not found
PSR-4 映射不是模糊匹配，是字符串拼接：给定类名 MyCompanyUtilsHelper，Composer 会严格拼出 src/Helper.php 并检查是否存在。
-
autoload必须写在项目或本地包自己的composer.json顶层（不能嵌套），例如："autoload": { "psr-4": { "MyCompany\Utils\": "src/" } } - 命名空间末尾双反斜杠
\缺一不可："MyCompanyUtils"是非法 JSON 字符串转义，"MyCompany\Utils\"才对 - 路径值用
"src/"，别用"./src"或"src"；末尾斜杠能防止与同名文件（如src.php）冲突 - 类文件路径必须逐级对应命名空间：类
MyCompanyUtilsHttpClient→ 文件必须是src/Http/Client.php，大小写、层级、文件名全要一致 - 改完
autoload后必须手动跑composer dump-autoload，install或update不会触发这个动作（除非 autoload 本身是依赖变更带来的副作用）
Class not found 时先确认 autoload_psr4.php 是否已更新
Composer 把 PSR-4 映射写死在 vendor/composer/autoload_psr4.php 里，这个文件只有 dump-autoload 才会重写。开发中看到报错，第一反应不该是查路径，而是看这个文件里有没有你刚加的命名空间条目。
- 运行
composer dump-autoload（开发阶段不用加-o） - 打开
vendor/composer/autoload_psr4.php，搜索你的命名空间前缀，确认是否已写入 - 如果用了 Laravel，还要额外检查：本地包是否提供了
ServiceProvider？是否已在config/app.php的providers数组中注册？Composer 不处理这部分 - 别在
require 'vendor/autoload.php'前就 new 类，也别用include或require_once手动引 src 下的文件——这绕过了 autoload 机制，后续依赖注入或测试会崩
