90%的Composer本地调试失败源于symlink未生效或autoload未重建；name和路径须字节级匹配，本地包composer.json必须含"options": {"symlink": true}，且需手动执行composer dump-autoload -o并清理缓存。
本地调试 Composer 包失败，90% 是 symlink 没生效或 autoload 没重建，不是代码没改、也不是 Composer 没装上。
path 仓库配置后 require 失败：name 和路径必须字节级一致
Composer 不做模糊匹配，name 字段大小写、分隔符（只允许短横线 -）、vendor 名必须和 require 中声明的字符串完全相同；路径则必须指向含 composer.json 的目录，且是相对于主项目 composer.json 的位置。
-
"acme/utils"≠"Acme/utils"≠"acme_utils" -
"url": "../my-pkg/"（末尾带/）会被静默忽略——删掉斜杠 - Windows 下路径含中文或空格，某些 PHP 版本会解析失败
- 验证方式：运行
composer show acme/utils，输出中必须有source: path ../my-pkg
改了代码但没生效：symlink 创建失败且无提示
path 类型默认尝试创建符号链接，失败就 fallback 到复制（copy），结果你改本地源码，vendor/ 里仍是旧副本——这是最隐蔽的坑。
- 关键配置不在主项目，而在本地包自己的
composer.json中："options": {"symlink": true} - Windows 必须以管理员身份运行终端，否则
symlink创建失败且不报错 - Docker 场景需加
--cap-add=SYS_ADMIN，且挂载方式要透传 symlink 权限（不能用-v $(pwd)/../pkg:/pkg） - 验证是否真用了 symlink：
ls -la vendor/acme/utils（Linux/macOS）或dir vendorcmeutils（Windows），看到->或JUNCTION才算成功
类找不到（Class not found）：autoload 没更新，不是包没装
Composer 安装 path 包时只建 symlink，但不会自动重生成自动加载映射。即使路径对、symlink 成功，new AcmeUtilsHelper() 仍可能报错。
- 必须手动执行
composer dump-autoload -o（加-o强制优化，避免 dev 模式缓存干扰） - 检查本地包
composer.json的psr-4键值末尾是否有反斜杠："Acme\": "src/"✅，"Acme": "src/"❌ - 路径值不能带点号：
"./src/"或"src/"都非法，必须是纯相对路径如"src" - 确认入口脚本引入的是
require __DIR__ . '/vendor/autoload.php';，不是错位的../vendor/autoload.php
缓存导致“看似没更新”：clear-cache 不清 vendor 和 vcs 快照
composer clear-cache 只清 ~/.composer/cache/files/ 和 provider 索引，对 path 包完全无效——它不碰 vendor/ 下的 symlink，也不删 Git 快照。
- 强制刷新本地包元数据：删掉
vendor/acme/utils目录，再跑composer update acme/utils --no-cache - 同时清理 Git 缓存：
rm -rf ~/.composer/cache/vcs/*（Linux/macOS）或对应 Windows 路径 - 验证是否真重载：加
-vvv运行，日志里应出现Reading ./../my-pkg/composer.json，而不是Using version x.x.x from cache - CI/Docker 中禁用 path 仓库——它们不支持 symlink，应改用真实版本号 + 私有镜像
真正卡住你的，往往不是 Composer 本身，而是 symlink 是否建立、autoload 是否重建、缓存是否残留这三个环节中任意一个被忽略。尤其在 Docker 或 Windows 下，options: {symlink: true} 写在本地包里这个动作，90% 的人会漏掉。
