Composer dump-autoload 卡在文件扫描阶段最常见的原因是遇到权限异常、语法错误或无法读取的 PHP 文件，如 .bak/.swp 文件、含 BOM 的 UTF-8 文件或无
为什么 composer dump-autoload 会卡在文件扫描阶段？
最常见原因是 Composer 在遍历 vendor/ 或自定义 autoload 路径时，遇到无法读取、权限异常或语法错误的 PHP 文件。它不会跳过——而是直接抛出 ParseError 或 Warning 并中断。尤其当项目混入了未完成的调试文件（如 test.php.bak）、IDE 临时文件（.php.swp）或含 BOM 的 UTF-8 文件时，token_get_all() 解析就会失败。
- 检查
composer.json中的"autoload"和"autoload-dev"字段是否引用了不存在的目录 - 运行
composer dump-autoload -vvv查看最后成功扫描的文件路径，定位卡点 - 临时重命名可疑目录（如
tests/或legacy/），再试一次，快速隔离问题源
如何识别被误扫的非标准 PHP 文件？
Composer 默认扫描所有 *.php 文件，不校验是否可执行或是否含合法 PHP 标签。如果你在 autoload 路径下放了 config.example.php、routes.php.txt 或带注释头但无 的模板文件，它都会尝试解析。
- 用
find vendor/my/package/src -name "*.php" -exec php -l {} ; 2>/dev/null | grep -v "No syntax errors"批量检测语法 - 在
composer.json中显式排除干扰项："autoload": { "psr-4": { "App\": "src/" }, "exclude-from-classmap": ["src/Config/example.php", "src/Helpers/old_*.php"] } - 避免在 autoload 目录中存放
.php后缀的配置/模板/文档文件
composer dump-autoload --no-scripts 有用吗？
没用。这个参数只跳过 post-autoload-dump 等脚本钩子，不影响文件扫描与类映射生成本身。真正影响解析流程的是 --classmap-authoritative 或 --optimize：它们会强制走 classmap 模式，绕过 PSR-4 动态路径查找，反而更容易暴露文件级问题——因为所有文件都会被无差别 tokenized。
- 加
--verbose可看到每个被加载的文件路径，比默认输出多一层上下文 - 加
--dry-run不写入vendor/autoload.php，但依然会完整扫描并报错，适合安全排查 - 若错误信息含
PHP Parse error: syntax error, unexpected '...' in ...，说明某文件存在 PHP 7.4+ 特性但当前环境是旧版本
类名与文件路径不匹配导致的静默失败
PSR-4 规范要求类名严格对应路径，但 Composer 不会在 dump-autoload 阶段校验这点——它只生成映射。真正出问题是在运行时 class_not_found。不过，如果某个文件里声明了多个类、或类名拼写错误（比如 class UserRepositoy），Composer 仍会把它加入映射，后续自动加载就会失败。
- 用
php -r "echo get_declared_classes() | grep -i user;"检查运行时是否真加载了该类 - 查看生成的
vendor/composer/autoload_psr4.php，确认目标命名空间是否出现在键中 - 用
composer show --platform确保当前 PHP 版本支持代码中使用的语法（如短闭包、属性类型）
实际排查时，90% 的 case 都卡在「某个不该被扫的 .php 文件」或「某个目录权限被 Docker / SELinux 锁死」。先看 -vvv 输出末尾，再查那个文件本身，比改配置快得多。
