“files”配置使composer在autoload.php初始化时立即加载指定PHP文件，实现全局函数调用；需路径正确、无输出、无运行时依赖，修改后须执行composer dump-autoload生效。
直接在 composer.json 里配 "files" 是最轻量的全局函数加载方式，但容易因路径错误或加载时机不对导致 Call to undefined function 错误。
files 配置项的作用和触发时机
"files" 是 Composer 的自动加载机制之一，它会在每次执行 composer dump-autoload（或安装/更新时）生成一个硬编码的 autoload_files.php 文件，并在 vendor/autoload.php 中被立即 require。这意味着：它不是按需加载，而是「启动即载入」——所有列在 "files" 里的 PHP 文件，只要引入了 vendor/autoload.php，就会无条件执行一遍。
- 适合放纯函数定义（不能有运行时逻辑、不能依赖未加载的类）
- 不支持命名空间或 PSR-4 映射，只认物理路径
- 路径是相对于
composer.json所在目录的相对路径 - 修改后必须重新运行
composer dump-autoload才生效
如何正确配置 files 并避免常见报错
在 composer.json 的 "autoload" 或 "autoload-dev" 段中添加 "files" 数组，值为字符串路径列表。注意路径必须存在且可读，否则 dump-autoload 会失败并报错：Warning: require(...): failed to open stream。
{ "autoload": { "files": [ "src/Helpers/functions.php", "src/Constants/status_codes.php" ] } }- 路径不要以
/开头（否则会被当成绝对路径，大概率出错） - 不要写
./src/...，Composer 不解析.，直接写src/... - 确保文件末尾没有输出（如
echo、print_r），否则可能污染 JSON 响应或导致 headers already sent - 如果函数名冲突（比如两个
files都定义了str_slug()），后加载的会覆盖前一个，且无警告
为什么 dump-autoload 后函数还是找不到？
最常见原因是路径拼写错误或未重新生成 autoload 文件。Composer 不会监控 "files" 列表里的文件内容变化，只认配置是否写进 autoload_files.php。
- 检查
vendor/composer/autoload_files.php是否已包含你新增的路径（格式类似$vendorDir . '/../src/Helpers/functions.php'） - 确认你的代码确实引入了
vendor/autoload.php（有些脚本会跳过它，改用require 'vendor/autoload.php'写法没问题，但若用了include_once而非require，失败时静默） - CLI 环境下执行
php -d display_errors=1 your_script.php查看是否抛出require失败的 warning - 如果你在测试中用
require_once 'vendor/autoload.php'，记得每次改完composer.json都要重跑composer dump-autoload
files 和 include/require 的本质区别
"files" 本质是让 Composer 把你的文件“塞进”自动加载流程，和手写 require 'src/Helpers/functions.php' 看似一样，但关键差异在于加载顺序和作用域：
- 手写
require在执行到那行才加载，可控；"files"在autoload.php初始化阶段就执行，不可跳过 -
"files"加载的文件中定义的函数，在任何地方都能直接调用（包括其他类的静态方法里），而手写require只对当前文件作用域有效（除非重复 require） - 如果多个包都用
"files"定义同名函数，Composer 不做去重或提示，最终行为取决于autoload_files.php中的排列顺序
真正容易被忽略的是："files" 加载的文件不能依赖 $GLOBALS 或 $_SERVER 等运行时上下文——因为它们可能在 CLI、Web、测试等不同环境中被提前载入，此时超全局变量状态不稳定。