composer 的 include-path 自 2.0 起已彻底废弃并静默忽略，因其与 psr-4/autoload 冲突且维护成本高；应改用 autoload.files 加载全局脚本或 psr-4 规范组织类。
Composer 的 include-path 已被废弃，自 Composer 2.0 起完全失效，任何依赖它来加载类或脚本的配置都会静默忽略。
为什么 include-path 不再起作用
Composer 早期（v1.x）曾通过 include-path 字段在 composer.json 中声明全局包含路径，供 require 或 include 直接使用。但该机制与 PSR-4/Autoload 设计冲突，且无法解决命名空间与文件路径映射问题，维护成本高。Composer 团队在 v2.0 中彻底移除了该字段解析逻辑——即使你写上，composer install 也不会报错，但也不会生效。
常见错误现象：
– 本地开发时 require 'SomeHelper.php' 暂时能运行（靠的是 PHP 自身的 include_path 配置或相对路径）
– 切换环境或部署后报 Warning: require(): failed to open stream
– composer dump-autoload -o 后依然找不到文件
替代方案：用 autoload.files 加载全局脚本
如果你原本依赖 include-path 来引入工具函数、常量定义或启动脚本（如 src/helpers.php），应改用 autoload.files。它会在每次 composer autoloader 初始化时自动 require_once 指定文件，且不受命名空间限制。
实操建议：
- 在
composer.json中添加："autoload": { "files": [ "src/helpers.php", "src/constants.php" ] } - 执行
composer dump-autoload生效（开发中可加-a参数强制重载） - 注意：路径是相对于
composer.json所在目录的，不能用../跨项目引用；若需软链接或外部路径，应通过符号链接或构建脚本预处理 - 性能影响：这些文件在每次请求 autoload 初始化时都会加载，避免放大量逻辑或 IO 操作
替代方案：用 PSR-4 + 命名空间代替“伪全局”类
如果你曾把工具类放在 include-path 下，然后直接 new Helper() 调用，说明实际需要的是可自动加载的类——这不是路径问题，而是自动加载配置缺失。
实操建议：
- 将类文件移到标准结构下，例如
src/Utils/ArrayHelper.php，并声明命名空间：namespace AppUtils;
- 在
composer.json中配置："autoload": { "psr-4": { "App\": "src/" } } - 使用时显式引入：
use AppUtilsArrayHelper;
或完整限定名AppUtilsArrayHelper::flatten() - 不要为了“省 use”而把所有工具类塞进根命名空间（
""），这会破坏可读性和 IDE 支持
兼容旧代码的临时过渡技巧
如果遗留项目大量使用 require 'Helper.php' 且无法立即重构，可借助 autoload.files + 符号链接或包装文件兜底，但仅限过渡：
- 创建
legacy-includes/目录，把原include-path下的文件软链进来（Linux/macOS）或复制（Windows） - 在
autoload.files中列出它们，确保路径稳定 - 同时搜索代码中所有裸
require/include，逐步替换为命名空间调用或__DIR__ . '/path'显式路径（更可靠） - 切勿修改 PHP 的
include_pathini 设置来“恢复”旧行为——这会让部署环境强耦合，且 Composer 不感知
真正容易被忽略的点是：很多团队以为 include-path 失效是因为没执行 dump-autoload，其实根本原因是字段已被硬编码忽略；另外，autoload.files 的路径解析不走 vendor，也不受 minimum-stability 影响，但它只对当前 root package 生效，子包里的 files 不会自动合并——如有嵌套依赖需各自声明。
