应改用composer self-update --local避免权限问题，国内加--mirror提速，测试环境可用--snapshot跳过签名验证。
composer self-update 在 CI/CD 里卡住或报 Permission denied 怎么办
根本不是网络慢，而是它试图覆盖系统级 /usr/bin/composer，但非 root 用户没权限。CI 环境默认用普通用户运行，file_put_contents(/usr/bin/composer): failed to open stream: Permission denied 就是典型表现。
- 改用
composer self-update --local：把新版本装到当前项目目录下的composer.phar，完全绕过系统路径写入 - 国内服务器加
--mirror https://mirrors.aliyun.com/composer/避免超时和 GPG 验证失败 - 测试环境可跳过签名验证：
composer self-update --no-interaction --no-ansi --snapshot（生产禁用） - 确认
composer config --global home输出不是/root/.composer或/var/www/.composer——这些路径说明环境被污染，得重设全局配置
path 仓库本地包改了代码却没生效？symlink 和缓存必须一起清
你以为改了 ../my-package/src/Service.php，其实 PHP 加载的是 vendor/vendor/name/ 里的静态副本，因为 symlink 没建成功，或者 Composer 复用了旧缓存。
- 先验证是否真用了 path 模式：
composer show vendor/name输出里必须含source: path ../my-package - 删掉
vendor/vendor/name目录（不是整个vendor/），再跑composer update vendor/name --no-cache - 强制清 Git 缓存：
rm -rf ~/.composer/cache/vcs/*（Linux/macOS），Windows 对应清理%APPDATA%Composercache cs - Windows 下必须以管理员身份运行终端；Docker 要加
--cap-add=SYS_ADMIN，且挂载方式得支持符号链接（不能用-v $(pwd)/../pkg:/workspace/pkg这种） - 本地包自己的
composer.json必须有"options": {"symlink": true}，主项目的配置不生效
autoload 映射写了却 Class not found？三处大小写与路径拼接必须严丝合缝
不是 Composer 没读配置，而是 PSR-4 的字符串截取逻辑在 Linux 上被大小写或路径偏差击穿。比如 namespace AppHttpControllers; 对应文件 src/Http/Controllers/HomeController.php，漏一个 Controllers 或写成 controllers，就直接静默失败。
- 运行
php -r "require 'vendor/autoload.php'; var_dump(class_exists('AppHttpControllersHomeController'));"直接验证 autoload 是否覆盖该类 - 检查
vendor/composer/autoload_psr4.php里映射值是不是$baseDir . '/src'这种表达式，并确认$baseDir实际指向的物理路径存在且可读 -
composer dump-autoload -v | grep -A5 'App\'看是否扫描到该命名空间；如果压根没出现，说明composer.json有语法错误（多逗号、BOM、单引号） - PSR-4 键必须以反斜杠结尾：
"App\": "src/"✅，"App": "src/"❌；路径只能是相对项目根的src/，不能是./src/或/full/path/src/
换镜像源后 composer require 还连 Packagist？缓存不清理等于白配
改完 repositories 或 config 后不清理缓存，Composer 会继续用旧的 packages.json 快照，日志里甚至看不到镜像地址。
- 必须按顺序执行：
composer clear-cache→composer require monolog/monolog -vvv - 在
-vvv日志里搜索Downloading，确认 URL 是镜像站地址，例如https://mirrors.aliyun.com/composer/p2/monolog/monolog.json - 检查
composer config --list输出，确认repositories字段已生效；若仍无效，临时运行composer config --unset repositories再重配 - 私有仓库配置中
{"packagist.org": false}必须作为独立对象放在repositories数组末尾，嵌套或写成"packagist": false都会被忽略
实际排查时最容易被跳过的点：不是看命令有没有报错，而是看 composer show 和 composer dump-autoload -v 的输出是否真正反映出你的预期配置。很多问题表面是“不生效”，实则是配置没被读、缓存没被破、或 symlink 根本没建起来。
