迁移项目时必须删除 vendor 和 composer.lock 后再执行 composer install；修改 autoload 配置后需运行 composer dump-autoload -o；注意 php 扩展缺失、路径大小写及符号链接兼容性问题。

composer install 之前必须删掉 vendor 和 composer.lock

迁移项目时，很多人直接复制整个目录（包括 vendor），结果运行时报错：类找不到、版本冲突、甚至 Class not found。根本原因是 vendor 是平台/环境相关产物，不能跨机器复用；而 composer.lock 记录的是旧环境生成的精确依赖树，如果 PHP 版本、扩展或平台差异较大，它反而会锁死不兼容的旧包。

正确做法是：

• 删除 vendor/ 目录和 composer.lock 文件
• 确认新环境已安装匹配的 PHP 版本（检查 php -v 和 composer --version）
• 运行 composer install —— 它会根据 composer.json 重新解析依赖，并生成适配当前环境的新 composer.lock

autoload 配置变更后必须 dump-autoload

改过 composer.json 里的 "autoload" 或 "autoload-dev"（比如新增了 psr-4 映射、调整了路径），不执行 composer dump-autoload，PHP 就永远找不到你新加的类。

常见触发场景：

• 新建了 app/Support/ 目录并映射到 "App\Support\": "app/Support/"
• 把测试类从 tests/ 移到 src/Tests/，但没更新 autoload 配置
• 切换了自动加载类型（如从 classmap 改成 psr-4）

执行命令：composer dump-autoload -o（加 -o 启用优化模式，生成静态映射表，提升性能）

PHP 扩展缺失会导致 autoload 失败但报错不明确

有些包在 autoload 阶段就依赖特定扩展（比如 ext-intl 或 ext-mbstring），而 Composer 不会在 dump-autoload 时校验这些。结果就是：命令执行成功，但运行时抛出 Class 'SymfonyPolyfillIntlIdnIdn' not found 这类看似“类不存在”，实则是底层扩展缺失的错误。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

排查建议：

• 运行 php -m 检查必需扩展是否启用（重点关注 intl, mbstring, curl, json, xml）
• 查看目标框架或核心包的 composer.json 中 "ext-xxx" 的 require 声明
• 在新环境中运行 composer check-platform-reqs（Composer 2.2+）快速核对

Windows 迁移到 Linux 时注意路径大小写与符号链接

Windows 文件系统不区分大小写，Linux 区分。如果 composer.json 里写了 "App\Http\Controllers\": "app/Http/Controllers"，但实际目录名是 app/http/controllers，Windows 下能跑通，Linux 下 dump-autoload 会生成错误映射，运行时直接 Class not found。

另外，某些包（如 symfony/flex）在安装时会创建符号链接（public/index.php → vendor/symfony/runtime/...），Windows 默认不支持，迁移后需手动重建或改用相对路径引用。

应对方式：

• 统一使用小写目录名（app/http/controllers）并同步更新 autoload 配置
• 避免在 vendor 外依赖符号链接，改用 require_once 或配置化路径
• Linux 上执行 composer install 后，用 find vendor/ -type l 检查残留 Windows 符号链接

autoload 文件不是“生成一次就一劳永逸”的缓存，它是环境、配置、代码结构三者共同作用的结果。任何一项变了，就得重来——尤其是跨平台、跨 PHP 版本、或修改了命名空间映射的时候。