files 作用是让 Composer 在自动加载时无条件一次性包含指定 PHP 文件，仅执行 require_once，适用于全局函数、常量、初始化逻辑等无法封装为类的场景。
files 加载方式在 composer.json 中的作用，是让 Composer 在每次自动加载（autoload）时，**无条件、一次性地包含指定的 PHP 文件**。它不依赖命名空间或类名映射，也不参与 PSR-4/PSR-0 类查找，只做最原始的 require_once 操作。
什么时候必须用 files？
适用于那些无法或不该被封装成类的全局函数定义文件，比如：
- 工具函数集合（
helpers.php、str_helpers.php） - 常量定义文件（
constants.php） - 需提前执行的初始化逻辑（如设置错误处理器、修改
mb_internal_encoding） - 兼容旧项目中大量裸函数调用，又不想重构为静态方法的场景
files 和 psr-4 的关键区别
files 是「立即执行」，psr-4 是「按需加载」——这点决定了它们不能互相替代：
-
files列表里的文件，在composer dump-autoload后会被写入vendor/composer/autoload_files.php，并在ComposerAutoloaderInit初始化阶段被require_once一次，之后全程驻留内存 -
psr-4映射的文件，只有在首次使用对应类时才被加载，且每次都是新实例（无副作用） - 如果把函数定义放在
psr-4目录下，而没用files引入，调用时会报Call to undefined function
配置写法与常见坑
在 composer.json 的 autoload 或 autoload-dev 下声明：
{
"autoload": {
"files": [
"src/helpers.php",
"src/constants.php"
]
},
"autoload-dev": {
"files": [
"tests/test_helpers.php"
]
}
}
注意以下易错点：
- 路径是相对于
composer.json所在目录的，不能用./src/或绝对路径 - 文件必须存在，否则
composer dump-autoload会静默失败，但运行时抛出Warning: require_once(...): failed to open stream - 多个
files之间有执行顺序，靠数组顺序决定；若b.php依赖a.php里定义的函数，a.php必须排在前面 - 修改
files后必须手动执行composer dump-autoload，否则新文件不会生效
为什么不用 include 或 require 手动引入？
手动引入看似简单，但破坏了 Composer 的统一加载机制，带来三个实际问题：
- 测试环境和生产环境容易漏掉某处引入，导致函数未定义
- CI/CD 流程中难以保证所有入口都覆盖了相同引入逻辑
- 无法被 IDE（如 PHPStorm）识别为自动可用函数，补全和跳转失效
用 files 是唯一能让函数“对整个项目透明可用”的 Composer 原生方案。真正麻烦的不是配置，而是确保这些全局函数没有命名冲突、不污染全局作用域、不依赖未初始化的上下文——这些得靠人来设计，Composer 只负责稳稳地把它载入。
