Composer 不管理 include_path，应通过 autoload 配置或运行时 set_include_path 修复；错误常因手动 require 未自动加载文件所致，需区分使用 psr-4/classmap、files 字段或临时调整 include_path。

Composer 本身不管理 PHP 的 include_path，所以直接靠它“修复”包含路径错误是走错方向——真正要动的是自动加载机制或运行时配置。

为什么 include_path 错误常被误认为 Composer 问题

这类错误（如 Warning: require(): open_basedir restriction in effect 或 failed to open stream: No such file）往往出现在手动 require/include 了未被 Composer 自动加载的文件时，比如：

• 项目根目录下写了 require 'config.php';，但没加路径前缀
• 第三方包用了 require_once 'SomeLegacyClass.php';，且依赖 include_path 查找
• php.ini 中 include_path 被清空或限制过严（尤其在共享主机或 Docker 容器中）

用 composer.json 的 autoload 替代 include_path

Composer 的设计哲学是「按命名空间自动加载」，不是靠 PHP 的 include_path。只要文件被正确声明进 autoload，require 就不该手动写。

• 类文件：用 "psr-4" 或 "classmap" 声明，例如：

  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }

• 全局函数或配置文件：用 "files" 字段，它会在每次 composer dump-autoload 后被无条件引入

  "autoload": {
    "files": ["src/helpers.php", "config/database.php"]
  }

• 改完记得运行 composer

  

  dump-autoload（开发时可加 -o 生成优化后映射）

临时绕过但不推荐：运行时修改 include_path

仅适用于无法改造的遗留代码（比如某些 CMS 插件），且必须在 require 前执行：

• 在入口文件（如 index.php）顶部加：

  set_include_path(get_include_path() . PATH_SEPARATOR . __DIR__ . '/vendor/some-legacy-lib');

• 注意顺序：get_include_path() 要放在前面，否则会覆盖默认路径（如 /usr/share/php）
• Docker 或 CLI 场景下，可能需在 php.ini 中显式设 include_path = ".:/path/to/vendor"，但会削弱隔离性

检查和验证当前 include_path 实际值

别猜，直接输出看：

• 运行 php -i | grep include_path 查 CLI 环境
• 在 Web 脚本里加 var_dump(get_include_path());
• 如果返回空字符串或只有 .，说明没继承系统默认值，常见于 php_admin_value 强制覆盖的 Apache/FPM 配置

真正的难点不在怎么写命令，而在于分清哪些该进 autoload.files、哪些该重构为命名空间类、哪些必须妥协用 set_include_path——混用三者反而会让路径逻辑更难追踪。