autoload.files 加载的函数不生效常见原因有四：路径未基于 composer.json 目录、函数被重复声明、定义在条件分支中未执行、strict_types 导致运行中断；正确配置需在 composer.json 中声明相对路径并执行 dump-autoload。
Composer 可以自动加载自定义函数库，但必须通过 autoload.files 配置，且仅支持 PHP 文件（不能是 .inc 或无扩展名），且这些文件会在每次 Composer 自动加载初始化时被 require_once 一次。
为什么 autoload.files 加载的函数不生效？
常见原因不是路径写错，而是：
- 文件里定义了函数但没做命名空间隔离，而后续又重复 require 同一文件（比如手动 include 过）→ 导致 “Cannot redeclare function” 错误
- 文件路径是相对路径，写在 composer.json 里却没基于项目根目录写（Composer 总是以 composer.json 所在目录为基准解析路径）
- 函数定义在条件语句或函数体内（如 if (DEBUG) { function foo() {} }），Composer 加载时未满足条件，函数根本没注册
- 使用了 declare(strict_types=1) 但文件间类型不一致，导致运行时报错中断加载流程（虽不报 autoload 错，但后续函数不可用）
如何正确配置 autoload.files？
在项目根目录的 composer.json 中添加：
{
"autoload": {
"files": [
"src/Helpers/functions.php",
"app/Support/helpers.php"
]
}
}
然后执行：composer dump-autoload（开发时）或 composer install/composer update（部署时）
注意：
- 路径必须存在，且对 Web 服务器/CLI 用户可读
- 不支持通配符（如 "src/Helpers/*.php"）
- 修改后必须重新生成 autoloader，否则不会生效
- 若使用了 optimize-autoloader（即 composer install --optimize-autoloader），files 仍会正常加载，但不会被合并进 vendor/composer/autoload_files.php 的静态列表外——它始终走独立 require 流程
autoload.files 和 autoload.ps4 混用要注意什么？
两者加载时机不同：
- psr-4 是按需加载（类不存在时才触发）
- files 是「启动即加载」，无论你用不用里面定义的函数，它都会被执行一次
所以：
- 不要把耗时操作（如 DB 连接、文件扫描）写在 files 加载的文件里
- 避免在 files 文件中 new 某个 PSR-4 类，除非该类已确保能被自动加载（否则会 fatal error）
- 如果函数内部依赖某个类，建议用字符串类名 + class_exists() 做懒检查，而不是直接实例化
真正容易被忽略的是：一旦把函数放进 autoload.files，它就脱离了作用域控制——没有命名空间、无法被 use、不能被 class_alias 替换，出问题时也很难被 IDE 索引或静态分析捕获。
