use-include-path 在 Composer 2.0 起已被彻底移除，非弃用而是根本不存在；写入 composer.json 会直接报错“Unknown key”；老项目需手动维护 include_path 或改用 autoload.files 绝对路径引入。
use-include-path 在 autoload 中已彻底废弃
use-include-path 是 Composer 1.x 早期（约 2013–2015）为兼容 PHP 5.3–5.5 时期老项目设计的配置项，用于让 ClassLoader 尝试在 include_path 中查找类文件。但它从 Composer 2.0（2020 年底发布）起被完全移除，且不再有任何加载逻辑——不是“不推荐”，是根本不存在。你在 composer.json 的 autoload 段里写 "use-include-path": true，composer dump-autoload 会直接报错：Unknown key "use-include-path" in autoload section。
老项目想用 include_path，得绕过 Composer 自动加载
如果你的原生 PHP 项目大量依赖 include_path（比如 require 'DB.php' 且靠 set_include_path('./lib') 支撑），Composer 不会、也不能接管这部分逻辑。它只管自己生成的 vendor/autoload.php 和你声明的 autoload 规则。
可行做法是手动维护路径并显式引入：
- 在入口文件顶部先调用
set_include_path()，确保老代码能require到对应文件 - 不要把老库塞进
autoload.files后还指望它响应include_path查找——files是绝对路径或相对于composer.json的路径，和include_path无关 - 若老库中存在硬编码路径如
require_once 'config/database.php'，必须改成相对当前文件的路径，或统一用__DIR__构造，否则include_path对它无效
替代方案：用 files + 绝对路径兜底最稳
对于没有命名空间、不走 PSR 规范的老库（比如仅含 function db_connect() 或 class DB {}），autoload.files 是唯一可靠方式。它不查 include_path，也不做任何映射，只是在每次自动加载启动时无条件 require_once 列表里的每个文件。
立即学习“PHP免费学习笔记（深入）”；
示例（lib/legacy/composer.json）：
{
"name": "legacy/utils",
"autoload": {
"files": [
"functions.php",
"DB.php"
]
}
}
注意两点：
- 路径是相对于该
composer.json所在目录的，不是项目根目录 - 如果
functions.php内部又require 'config.php'，那个config.php必须和它在同一目录，或你得提前把该目录加进include_path——但这是你代码的责任，不是 Composer 的
为什么现在没人提 use-include-path 了
因为 PHP 5.6 之后 include_path 使用场景急剧萎缩；现代部署基本禁用它（安全考虑）；而 Composer 的 files 和 psr-4 足以覆盖所有合理加载需求。试图复活 use-include-path 相当于在 HTTPS 时代坚持配 FTPS——不是做不到，是整条链路都已弃用，强行接只会暴露更多边界问题。真正卡住老项目的，从来不是这个字段，而是类名冲突、全局函数污染、以及 require_once 路径硬编码到绝对位置。
