files路径必须相对于composer.json且大小写敏感，需手动执行composer dump-autoload生效，文件内禁止副作用逻辑，函数定义须防重复并建议加前缀。
files路径必须相对于composer.json，且大小写敏感
写在files数组里的路径，是从composer.json所在目录开始算的相对路径，不是从src/或vendor/起算。比如项目根目录下有src/helpers.php，那就要写"src/helpers.php"，不能写"helpers.php"或"../src/helpers.php"。
Linux/macOS/Docker 环境下路径严格区分大小写。若实际文件是app/helpers.php，但配置成"App/helpers.php"，composer dump-autoload不会报错，但运行时会抛出Failed to open stream: No such file or directory——错误堆栈指向ClassLoader.php，容易误判为 autoload 机制问题。
- 用
ls -l app/helpers.php确认真实路径和大小写 - Windows 下测试通过不等于 Linux 下可用，上线前务必在目标环境验证
- 路径中不能包含
..上溯符号，Composer 不允许跨出项目根目录
修改后必须手动执行composer dump-autoload
files配置不会热更新。改完composer.json后，不运行命令，vendor/autoload.php里就不会包含新路径，函数自然不可用。
常见静默失效场景：只改了 JSON、忘了执行命令；或执行了composer install但当前没有变更依赖（此时不会触发 autoload 重生成）。
- 开发阶段推荐用
composer dump-autoload，清晰明确 - 生产环境可加
--optimize参数，把所有files合并进vendor/composer/autoload_files.php，提升性能 - 加
echo "loaded";到目标 PHP 文件开头，跑一次脚本看是否输出，是最直接的生效验证方式
files里只能放纯定义，禁止副作用逻辑
files中的每个 PHP 文件会在每次require 'vendor/autoload.php'时被require_once执行一次——这意味着它不是“按需加载”，而是“无条件启动即执行”。
如果文件里写了echo、file_get_contents、数据库连接、new实例化等，这些代码会在 CLI 命令、Web 请求、甚至 PHPUnit 初始化阶段就运行，极易引发意外行为或致命错误。
- ✅ 允许：
function my_helper() { }、define('API_TIMEOUT', 5)、class_alias('OldClass', 'NewClass') - ❌ 禁止：
echo "init";、$client = new GuzzleHttp\Client();、require 'config.php'; - 多个文件有依赖关系时，靠数组顺序控制载入先后，被依赖的文件必须写在前面
函数重复定义会直接Fatal error，没有容错
PHP 不允许重复声明函数。files数组按顺序加载，若两个文件都定义了同名函数（如str_slug()），后加载的那个会触发Fatal error: Cannot redeclare str_slug()，整个 autoload 流程中断，连类都加载不了。
这个问题在合并多个旧项目、或引入第三方 helper 包时特别容易出现——你可能根本不知道某个函数已被别处定义。
- 用
function_exists('my_helper')包裹函数定义可临时规避，但属于掩盖问题，不推荐长期使用 - 函数命名尽量带项目/模块前缀，如
acme_str_slug()，比靠加载顺序更可靠 - 一旦函数开始需要依赖注入、环境判断或配置驱动，就该考虑封装成类+服务容器，而不是硬塞进
files
实际项目里最容易被忽略的，是files带来的隐式执行时机——它不挑上下文，不管你是跑单元测试、导出数据还是部署钩子，只要碰到了vendor/autoload.php，那些函数文件就一定会执行一遍。这点在写 CI 脚本或调试超时问题时，常常成为最后一块拼图。
