autoload.files 是唯一能实现全局函数自动载入的机制，因其在每次 autoload 初始化时无条件载入指定文件，而 PSR-4、classmap 等均不支持函数；需用固定路径数组配置，错误路径会静默失败。
Composer 的 autoload.files 是唯一能实现「全局函数自动载入」的机制，但它不支持通配符、不触发 PSR-4 自动发现，且一旦写错路径就会静默失败——没有报错，函数就是找不到。
为什么 autoload.files 是唯一选择
PHP 本身不支持像类那样按需加载函数文件；所有函数必须在调用前被 include 或 require 进来。Composer 只在 autoload.files 中声明的文件会在每次 composer autoload 初始化时被无条件载入（通过 vendor/autoload.php）。
- PSR-4 / PSR-0 只处理类，对函数完全无效
-
autoload.classmap也只映射类名到文件，不适用于函数 - 不能写成
"files": ["helpers/*.php"]—— 不支持 glob
正确配置 autoload.files 的写法
必须是相对于 composer.json 所在目录的**固定路径数组**，且路径需存在、可读、语法合法。推荐统一放在 src/Functions/ 下便于管理。
{
"autoload": {
"files": [
"src/Functions/helpers.php",
"src/Functions/validation.php",
"src/Functions/str.php"
]
}
}
- 路径必须是字符串，不能是变量或常量
- 建议全部使用正斜杠
/，Windows 下也兼容 - 修改后必须运行
composer dump-autoload才生效（不是install或update） - 如果路径错误，Composer 不会报错，但对应函数在运行时抛出
Call to undefined function
常见陷阱与调试方法
最常踩的坑不是写错配置，而是没意识到「载入时机」和「作用域污染」问题。
- 函数文件中不能依赖尚未载入的类（比如在
helpers.php里直接 new 一个 PSR-4 类）——此时 autoloader 还未完全就绪 - 多个
autoload.files文件之间若有同名函数，后载入的会覆盖前面的（PHP 函数不可重复声明） - 调试时可临时加一句
echo "loaded: " . __FILE__ . PHP_EOL;到函数文件头部，然后执行php -r "require 'vendor/autoload.php';"看是否输出 - 检查是否真被载入：运行
composer show --platform | grep autoload没用；应直接var_dump(get_included_files())查看列表
替代方案：什么时候该放弃 autoload.files
如果你的函数越来越多、开始出现条件加载、需要 DI 或依赖其他组件，说明它已超出「全局工具函数」范畴，该重构为服务类。
- 例如：
format_money()可以保留；但send_notification()含 Guzzle 依赖，就该变成NotificationService - 想按需加载？只能手动
require_once，Composer 不提供 lazy-function-load 机制 - 想跨包共享？把函数封装进独立包，并在它的
autoload.files中声明——别试图在主项目里硬 include 子包路径
真正难的不是写对那几行 JSON，而是判断哪些函数真的适合放进去：它们得足够稳定、无依赖、不随上下文变化。否则，越早移出去，后期越省事。
