根本原因是 symlink 未生效，导致运行时加载 vendor 中的静态副本而非源码；验证需用 ls -la 或 dir 检查是否为链接，且本地包 composer.json 必须配置 "options": {"symlink": true}。
本地path包改了代码，但dump-autoload后类还是找不到
这不是 dump-autoload 失效，而是你根本没走 symlink，而是在用 vendor 里的静态副本。Composer 对 path 包默认启用 symlink，但 Windows 需管理员权限、Docker 需额外配置，否则会静默 fallback 到 copy 模式。
验证方式：
- Linux/macOS 执行
ls -la vendor/vendor/name，看到->才是链接成功 - Windows 执行
dir vendor\vendor\name，看到JUNCTION或SYMLINKD - 如果显示普通文件夹，说明 symlink 创建失败，此时
dump-autoload再多次也无效——它只刷新 autoload 映射，不重建 symlink
修复要点：
- 本地包自己的
composer.json必须含"options": {"symlink": true} - Windows 用户必须以管理员身份打开终端再运行
composer install - Docker 中挂载路径需透传符号链接权限：
--cap-add=SYS_ADMIN，且宿主机目录需有read+execute权限
dump-autoload -v 根本不扫描你的命名空间
输出里压根没出现 App\ 或你配置的前缀，说明 autoload 配置压根没被读进去。不是路径写错，是 JSON 解析失败或配置位置错误。
常见硬伤：
-
composer.json里"psr-4": {"App": "src/"}—— 缺末尾反斜杠，必须是"App\" - 路径写成
"./src/"或"/full/path/src/"—— Composer 只认相对于项目根目录的纯路径，如"src/" -
autoload字段嵌在require或scripts下 —— 它必须是顶层字段 - 文件含 BOM、中文逗号、单引号、注释 —— 全删掉，用
composer validate直接定位错误行
类文件已改，但运行时仍加载旧逻辑
问题不在 Composer，而在 PHP 的 opcode 缓存。dump-autoload 生成了新映射，但 PHP 还在执行旧的 opcode，class_exists() 返回 true，new 却报错或行为异常。
排查命令（在目标环境直接运行）：
php -r "require 'vendor/autoload.php'; var_dump(class_exists('AppServicesUserService'));"
若返回 bool(true) 但实际调用出错，大概率是 opcode 缓存未清：
- 运行
php -r "opcache_reset();"（需opcache.enable=1） - PHP-FPM 环境下，重启服务比清缓存更彻底：
sudo systemctl reload php-fpm - Apache + mod_php 需确认 opcache 是否启用，仅重启 Apache 不一定生效
CI/CD 构建后 autoload 映射“看起来对”，但类加载失败
构建镜像时容易忽略两件事：一是 composer install 默认不触发 dump-autoload，二是 -o 生成的 classmap 是静态快照，路径错位会导致空数组。
典型陷阱：
- CI 脚本只跑
composer install --no-dev --optimize-autoloader，没加--classmap-authoritative→ Composer 仍 fallback 到 PSR-4 动态查找，而 $baseDir 计算可能指向构建临时目录 - 构建时把代码拷贝进容器，但
composer.json里配的是"App\": "app/"，实际代码在/app/src/→ 映射路径拼成/app/app/...，根本不存在 - 部署后没清 OPCache，或用了
opcache.revalidate_freq > 0，导致新 autoload 文件被忽略
可靠做法：构建阶段显式执行 composer dump-autoload -o --classmap-authoritative，并确保入口脚本中 require __DIR__ . '/vendor/autoload.php' 的 __DIR__ 指向正确根目录。
