Composer需通过autoload显式配置外部目录映射：psr-4要求路径相对composer.json且结构匹配命名空间；classmap适用于无命名空间或扁平目录；files用于全局函数/常量引入；修改后必须运行composer dump-autoload生效。
Composer 默认不支持直接把外部目录（比如 ./lib 或 ../shared-utils）自动映射到某个命名空间，必须通过 autoload 配置显式声明，且路径需为相对 composer.json 所在位置的路径。
如何用 psr-4 映射外部目录到自定义命名空间
这是最常用也最推荐的方式。关键点在于：psr-4 的 value 必须是目录路径（相对于 composer.json），且该路径下需有符合命名空间结构的子目录层级。
- 假设你想把
../my-common/src/映射到MyCommon\\命名空间 -
composer.json中写法必须是：{ "autoload": { "psr-4": { "MyCommon\\": "../my-common/src/" } } } - 执行
composer dump-autoload生效，不是install或update - 路径不能以
/开头（否则会被当作绝对路径，Composer 会忽略） - 若外部目录不在项目根同级，比如在
/var/shared/utils，则无法直接用psr-4—— Composer 不允许跨文件系统或绝对路径映射
classmap 适用于无命名空间或扁平结构的旧库
当你要加载的是纯函数文件、无命名空间的类，或目录结构混乱（比如所有 .php 文件都在同一层），classmap 是更稳妥的选择。
- 它不依赖文件路径与命名空间对应关系，只扫描并生成类名 → 文件路径的静态映射
- 配置示例：
{ "autoload": { "classmap": [ "../legacy-toolkit/", "./scripts/helpers.php" ] } } - 注意：
classmap条目支持目录或具体文件，但目录必须可读，且扫描时会递归包含所有.php文件 - 每次新增类文件后，必须重新运行
composer dump-autoload -o（加-o生成优化后的 classmap，否则开发时可能漏加载）
为什么 files 加载方式容易被忽略但很实用
当你只需要全局引入几个工具函数（如 helpers.php），又不想封装成类，files 是最轻量的方案 —— 它会在每次 autoload 初始化时无条件 require_once 这些文件。
- 配置示例：
{ "autoload": { "files": [ "src/functions.php", "../shared/constants.php" ] } } - 路径同样是相对于
composer.json的，不支持通配符 - 文件中不能有语法错误，否则整个 autoloader 启动失败，报错类似：
PHP Fatal error: Cannot declare function xxx, because the function is already declared（重复加载导致） - 适合放
define()、function_exists()包裹的函数、或仅含常量的文件
常见陷阱与验证方法
映射写完不生效？大概率卡在这几个地方：
- 没运行
composer dump-autoload—— 修改autoload后必须手动刷新，Composer 不会自动监听变更 - 路径拼写错误：比如写成
"MyCommon\\": "../my-common/src"（缺末尾/）在某些系统下仍能工作，但不规范；而写成"MyCommon\\": "/home/user/my-common/src/"则完全无效 - 命名空间声明不匹配：PHP 文件顶部必须写
namespace MyCommon;或namespace MyCommon\Utils;，否则即使路径对，类也找不到 - 验证是否成功：运行
composer show -p查看 autoload 映射列表；或临时加一行var_dump(class_exists('MyCommon\\Helper'));测试
外部路径的灵活性是以可维护性为代价的 —— 团队协作时，务必在 README 里写明这些路径依赖，否则别人 git clone 后直接 composer install 会静默失败。
