必须在 composer.json 的 autoload.files 中声明全局函数文件并运行 composer dump-autoload 才能生效；文件按数组顺序 include_once，需注意依赖顺序和副作用控制。
composer.json 里用 autoload.files 加载全局函数文件
Composer 不会自动识别或执行任意 PHP 文件，想让自定义的函数（比如 helpers.php）在项目任何地方直接调用，必须显式声明。最直接的方式是在 composer.json 的 autoload 段落中配置 files 数组。
它会在每次 Composer 自动加载器初始化时（即执行 require 'vendor/autoload.php' 时），无条件、一次性地 include_once 列出的每个文件——不依赖命名空间，也不检查类是否存在。
示例配置：
{
"autoload": {
"files": [
"src/helpers.php",
"src/functions/global.php"
]
}
}配置完后，**必须运行** composer dump-autoload（或简写 composer du）才能生效。否则新增的文件不会被加载。
为什么 files 加载顺序重要？
多个文件按数组顺序依次 include_once，所以函数定义不能互相依赖错序。比如 src/utils.php 里用了 src/helpers.php 中的 str_slug()，那 helpers.php 就必须排在 utils.php 前面。
常见陷阱：
- 把含
require或include的文件放进files，容易引发重复包含或路径错误 - 文件里用了未声明的命名空间别名（如
use DateTime;），但该文件本身不是类文件，PHP 不会自动解析use，会导致Class 'DateTime' not found - 文件中有顶层
return或exit，会中断自动加载流程，后续文件不执行
和 PSR-4 自动加载混用时要注意什么？
files 和 psr-4 是并列机制，互不影响，但行为完全不同：前者是立即执行，后者是按需加载类。如果你在 files 里引入了一个定义了类的文件，这个类就“永远在线”，哪怕没人用；而 PSR-4 下的同名类如果也被加载，就会触发 Fatal error: Cannot declare class X。
建议原则：
- 只把纯函数、常量、配置数组等无副作用代码放进
files - 不要在
files中new实例、调用服务、连接数据库——这些逻辑应封装进类，走 PSR-4 + DI - 如果函数文件本身依赖某个类，确保该类已通过 PSR-4 或其他方式可被自动加载，否则运行时报
Class not found
调试 files 是否真的加载了？
最简单的方法：在目标 PHP 文件顶部加一行 echo "helpers.php loaded\n";，然后执行一个 CLI 命令（如 php -r "require 'vendor/autoload.php';"）。如果看到输出，说明文件被加载；没输出，要么路径写错，要么没运行 composer dump-autoload。
也可以临时在 vendor/autoload.php 末尾加 var_dump(get_included_files());，看输出数组里有没有你的文件路径。
注意：files 只在 CLI 和 Web 请求中生效一次，不会因为路由切换或请求重发而重复加载；但如果用 Swoole、RoadRunner 等长生命周期框架，要特别小心全局函数被多次定义（此时应加 function_exists() 判断）。
