autoload.files 是 Composer 唯一合法的函数自动加载机制，仅通过 require_once 加载指定 PHP 文件，路径须相对于 composer.json 目录且必须存在，修改后需手动执行 composer dump-autoload 生效，严禁含副作用代码。
composer.json 的 files 字段是唯一合法入口
Composer 本身不支持函数自动加载，autoload.files 是它提供的唯一原生机制——不是“可选方案”，而是“别无选择”。你不能靠 PSR-4 映射函数，也不能用 classmap 绕过限制；写错、漏写、或寄希望于“自动发现”，结果都是函数调用时抛出 Fatal error: Uncaught Error: Call to undefined function。
这个字段只做一件事：每次加载 vendor/autoload.php 时，require_once 列表里的每个 PHP 文件。它不校验内容、不解析命名空间、不判断是否真有函数定义——只管执行。
-
files数组必须放在autoload下，路径始终相对于composer.json所在目录（通常是项目根目录） - 路径必须以
./或子目录开头，比如"src/functions.php"✅，"functions.php"❌（会被当成当前工作目录下的文件，不可靠） - 路径必须指向真实存在的 PHP 文件，不能是目录，也不能用未引号包裹的通配符（
"src/*.php"可用，但src/*.php会报 JSON 解析错误） - 文件里不能有语法错误，否则
composer dump-autoload不报错，但运行时直接 fatal，堆栈常卡在ClassLoader.php，容易误判为 autoload 机制故障
为什么执行了 composer dump-autoload 函数还是找不到
写了 files 并不等于生效。Composer 不监听配置变更，它只认 vendor/composer/autoload_files.php 里已生成的硬编码列表。这一步必须手动触发，且要确认三件事：
- 没运行
composer dump-autoload—— 修改composer.json后这步不可跳过 - 路径写错或文件不存在 —— Composer 静默跳过无效条目，不会警告，也不会报错
- 函数名冲突 —— 比如自己定义了
str_contains()，而 PHP 8.0+ 已内置，运行时抛Cannot redeclare str_contains() - 文件里用了
declare(strict_types=1)，但调用处传参类型不匹配，导致致命错误而非预期逻辑失败
files 加载时机与副作用风险
files 中的文件会在所有 PSR-4/PSR-0 类加载器注册完毕后、首次类访问前被 require_once。这意味着它适合放纯函数和常量，但极度忌讳副作用：
- ✅ 允许：
function foo() { }、define('APP_ENV', 'dev')、class_alias('OldClass', 'NewClass') - ❌ 禁止：
echo 'init';、new PDO(...)、file_get_contents(__DIR__ . '/config.json')、$_ENV['DB_HOST']直接读取（环境可能未初始化） - ⚠️ 特别注意：不要在
files里require其他文件 —— 子文件加载时机不可控，容易引发依赖断裂或重复加载 - ⚠️ 多个文件按数组顺序加载，后加载的可以覆盖前面同名函数，但 PHP 不允许重声明，所以重复定义会直接 fatal
什么时候该停用 files 改走其他路
当函数开始出现这些信号，就说明 files 已经撑不住了：
- 函数内部需要读配置、查环境变量、依赖服务容器 —— 它不再是“全局工具”，而是“业务逻辑片段”
- 多个项目共用同一套函数，靠复制粘贴维护 —— 应该打包成独立 Composer 包，用 PSR-4 +
autoload-dev管理 - 某些函数只在测试或命令行场景下需要 ——
files是全量加载，无法条件触发，得换autoload-dev或手动require - 函数越来越多，没人能说清哪些可用、哪些已废弃、哪些必须配合特定上下文 —— 这时候文档和命名约定比 autoload 机制更关键，而
files对这两者毫无约束力
最常被忽略的一点：files 不提供任何加载隔离或作用域控制。它把函数扔进全局空间，一次写错，整个应用都可能受影响。
