Composer如何加载非PSR规范的PHP文件？ (files/classmap自动加载)

files 加载方式适合非PSR规范文件，因为composer的PSR自动加载器无法识别无类名、无命名空间的纯函数或常量文件，而files配置可在autoload初始化时通过require_once强制提前载入这些文件。

为什么 files 加载方式适合非PSR规范文件

Composer 默认只处理符合 PSR-4/PSR-0 的类自动加载，遇到纯函数文件（如 helpers.php）、全局常量定义或过程式逻辑时，它不会自动包含——这些文件没类名、没命名空间，PSR 自动加载器根本找不到入口。这时必须用 files 方式，在 Composer 初始化阶段就强制 require_once 这些文件，确保它们提前载入。

在 composer.json 中配置 files 自动加载

把目标 PHP 文件路径写进 "autoload": {"files": [...]} 数组，路径是相对于 composer.json 所在目录的相对路径。执行 composer dump-autoload 后，Composer 会在每次加载自动加载器时（比如 require 'vendor/autoload.php'）一并执行这些文件。

• 路径必须存在且可读，否则 composer dump-autoload 不报错，但运行时会触发 Warning: require(): Failed opening required
• 不支持通配符（如 *.php），每个文件都得单独列出来
• 多个文件按数组顺序依次加载，有依赖关系时要注意先后顺序（例如先定义常量，再加载用到它的函数）

{     "autoload": {         "files": [             "src/helpers.php",             "src/constants.php",             "legacy/compat_functions.php"         ]     } }

classmap 能否用于非类文件？

不能。虽然 classmap 生成的是“文件路径 → 类名”的映射表，但它只扫描含 class、Interface、trait 或 enum 声明的 PHP 文件；纯函数或变量定义的文件会被跳过。即使你手动把这类文件加进 autoload.classmap 数组，Composer 也不会在自动加载时 require 它们——因为 classmap 加载器只响应 class_exists() 等类查找操作，对函数调用无感知。

• 验证方法：运行 composer dump-autoload -o 后查看 vendor/composer/autoload_classmap.php，确认你的目标文件是否出现在数组中
• 如果没出现，说明它被跳过了；强行补进去也没用，加载器不会触发
• 想让函数可用，唯一可靠路径仍是 files

加载时机与常见陷阱

files 列表中的文件在 vendor/autoload.php 被引入时立即执行，不是懒加载。这意味着：

立即学习“PHP免费学习笔记（深入）”；

• 所有代码会无条件运行，包括 echo、define()、function_exists() 检查等——别在里面写输出语句，否则可能破坏 API 响应或 CLI 输出
• 不能依赖运行时参数（如 $_GET 或命令行 $argv），因为加载发生在脚本逻辑之前
• 若文件中定义了函数，而项目其他地方又重复定义（比如测试时多次 require），会直接报 Fatal Error: Cannot redeclare
• 修改 files 后必须重新运行 composer dump-autoload，否则变更不生效

非 PSR 规范文件的加载本质就是“提前一次性包含”，没有绕过这个机制的取巧办法。关键在于控制好文件内容的幂等性，以及明确它在整个加载链中的位置。