本地包修改未生效，主因是vendor中未建立软链接而fallback至复制模式；需用ls -la（Linux/macOS）或dir（Windows）验证是否含“->”或“JUNCTION”，否则必须显式配置"options":{"symlink":true}并执行composer update --no-cache清理缓存重装。
本地改了包代码，vendor/ 里没变，不是 Composer 没反应，而是它根本没重新映射——默认 fallback 到复制模式，或 symlink 没真正建立。
确认 vendor 目录下是不是软链接
这是最常被跳过的验证步骤。不检查这个，后面所有操作都是徒劳。
- Linux/macOS：运行
ls -la vendor/vendor-name/package-name，看到->指向本地路径才算成功；如果只是普通文件夹，说明 symlink 失败，已 fallback 到 copy 模式 - Windows：运行
dir vendor endor-namepackage-name，必须看到JUNCTION或SYMLINKD字样；否则你改的永远是源码，跑的永远是 vendor 里的副本 - 关键原因：本地包根目录下的
composer.json缺少"options": {"symlink": true}—— 这句必须有，否则 Composer 在 Windows、Docker、甚至某些 macOS 权限场景下会静默放弃 symlink
强制刷新 path 映射，别只清 cache
composer clear-cache 对 path 类型仓库基本无效，它不碰 vendor、不重读 repositories、也不清理 Git 元数据快照。
- 删掉 vendor 中对应包：
rm -rf vendor/vendor-name/package-name（不是整个vendor/） - 删掉 Composer 的 VCS 缓存：
rm -rf ~/.composer/cache/vcs/*（Linux/macOS）或对应 Windows 路径 - 再执行：
composer update vendor-name/package-name --no-cache，加--no-cache强制绕过所有缓存层 - 验证日志：加
-vvv参数运行，应看到Reading /path/to/local/package/composer.json，而不是Using version x.x.x from cache
改完本地包代码后怎么让运行时立刻生效
即使 symlink 建立成功，改了类名、新增了类、或调整了 autoload 配置，PHP 自动加载器也不会自动感知。
- 先确保本地包的
composer.json中autoload配置正确（比如 PSR-4 前缀末尾带反斜杠："App\": "src/"） - 运行：
composer dump-autoload—— 这步必须做，否则新类根本不会进vendor/composer/autoload_classmap.php或autoload_psr4.php - 如果线上环境用 OPCache，还得清 OPCache 或重启 PHP-FPM；仅刷新页面或 reload nginx 不起作用
- 别依赖
composer install：它只按composer.lock还原，不会重新解析本地包结构
为什么 composer update 有时还是拉远程包
主项目 composer.json 的 repositories 配置可能被忽略，或与 require 版本不匹配。
- 检查
repositories是否为有效 JSON 数组，不能是空对象{}，也不能混入非法字段（如注释） - 运行
composer show vendor-name/package-name，输出中必须含source: path ../my-package，否则配置未生效 - require 中版本号必须是
dev-main这类分支别名，不能写^1.0或1.0.x-dev—— path 仓库不走语义化版本解析 - 确保本地包目录下有
composer.json，且其name和version（如"version": "dev-main"）与主项目 require 完全一致
最易被忽略的一点：Windows 用户在非管理员权限下、Docker 容器未启用 sys_admin 或挂载方式不对时，"symlink": true 会彻底失效，但 Composer 不报错——必须手动验证 dir 输出是否含链接标识，不能凭感觉认为“应该成了”。
