Composer 2.0起已彻底移除include-path配置，必须改用psr-4自动加载；需补全namespace、更新composer.json autoload配置、删除手动require，并注意tests/、bin/及框架引导文件中的残留依赖。
include-path 在 Composer 里早就没用了
Composer 从 2.0 版本起彻底移除了 include-path 配置项，不是“不推荐”，是直接报错：运行 composer install 时会提示 Unknown configuration setting "include-path"。它在 1.x 后期已被标记为废弃，但很多人没注意升级日志，直到换环境或重装依赖才暴露问题。
根本原因在于：include-path 是 PHP 自身的 include_path ini 设置的映射，而 Composer 的定位早已转向自动加载器驱动——所有类加载必须走 autoload 配置生成的 vendor/autoload.php，不再依赖全局路径污染。
psr-4 替代 include-path 的实际迁移步骤
旧项目若靠 include-path 把 src/ 或 lib/ 目录塞进 PHP 查找路径，现在得改用 psr-4 显式声明命名空间与目录映射。这不是简单替换配置，而是要对齐代码中的 namespace 声明。
- 检查所有被
include-path覆盖的目录下，PHP 文件是否含namespace—— 如果没有，先补上（比如统一设为App），否则psr-4加载失败 - 在
composer.json中删掉"include-path"字段，添加"autoload"：
"autoload": {
"psr-4": {
"App\": "src/"
}
}
- 运行
composer dump-autoload重新生成自动加载器 - 确认旧代码中
require 'SomeClass.php'这类手动引入全部删除，改用new AppSomeClass()或use AppSomeClass
为什么不能用 classmap 或 files 替代 psr-4
有人想绕开命名空间改造，直接用 classmap 扫描目录或 files 列出全局函数文件。这在技术上可行，但会埋下三个隐患：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
classmap不支持开发时动态新增类，每次加文件都得手动跑composer dump-autoload --optimize，破坏开发流 -
files只加载一次，无法按需加载，且无法处理命名冲突（比如两个helper.php） - 两者都不提供命名空间隔离，多人协作或集成第三方包时极易因类名重复导致覆盖或 Fatal Error
换句话说：用 psr-4 不是图标准，是图可维护性。哪怕项目目前只有 3 个类，也值得把 namespace 和目录结构对齐。
旧项目迁移时最容易漏掉的点
迁移完成跑起来不报错，不代表真成功。这些地方常被跳过：
- 测试文件（
tests/）往往也有自己的include-path依赖，同样要加进autoload-dev的psr-4 - 命令行脚本（如
bin/app）如果用require_once引入了 src 下的类，得改成require __DIR__.'/../vendor/autoload.php'; -
autoload-dev和autoload的映射前缀不能相同，否则生产环境也会加载测试类，造成意外副作用 - 某些框架（如早期 Laravel 4.x）自定义的加载逻辑可能硬编码了
include_path，得查 vendor 里的引导文件是否调用set_include_path()
真正卡住人的，从来不是配置怎么写，而是哪一行 require 没删干净，或者哪个 namespace 拼错了斜杠。
