autoload.files配置路径必须相对于composer.json且真实存在，不能用./或绝对路径；路径写错不报错但函数无法加载，需执行composer dump-autoload并确保入口文件引入vendor/autoload.php。
autoload.files 配置路径必须相对且真实存在
Composer 只认相对于 composer.json 所在目录的路径，不能用 ./src/helpers.php 或绝对路径。写错路径不会报错，但文件根本不会被加载——函数调用时直接抛 Fatal error: Call to undefined function。
实操建议：
- 路径写成
"src/helpers.php"这种纯相对形式，确保该文件在磁盘上真实存在、可读 - 不支持通配符，
"src/helpers/*.php"会被忽略，每个文件必须单独列出 - 执行
composer dump-autoload后，检查vendor/composer/autoload_files.php是否已把路径写入$files数组 - 若用 CI/CD 部署，应使用
composer install --no-dev（而非dump-autoload），否则可能漏掉autoload_files.php生成
函数重复定义是 runtime fatal，不是 autoload 错误
autoload.files 的文件会在每次请求初始化时被 require_once 一次。但如果该文件被其他地方（比如测试 bootstrap、手动 include、或框架早期 boot 流程）再次加载，就会触发 Cannot redeclare function。
常见踩坑点：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 测试中既配置了
phpunit.xml的bootstrap="vendor/autoload.php"，又在测试文件里写了require 'src/helpers.php' - helper 文件里用了
declare(strict_types=1)，而项目其他地方类型不一致，导致加载中断，函数注册失败 - 函数定义在条件分支中（如
if (env('DEBUG')) { function debug_dump() {} }），环境不满足时函数压根没声明
files 和 PSR-4 共存时加载顺序固定但依赖易断
autoload.files 总是比 PSR-4 先执行，这意味着：你能在 helper 函数里安全调用 class_exists()，但不能直接 new App\Services\UserService()——因为此时 PSR-4 加载器还没注册，类名解析会失败。
安全做法：
- 避免在
files加载的文件中实例化任何非内置类 - 如果必须依赖某个类，改用字符串类名 +
class_exists()懒检查，或封装成闭包延迟执行 - 多个 helper 文件有依赖关系时，数组顺序即加载顺序：
"src/functions.php"必须写在"src/helpers.php"前面，如果后者依赖前者定义的函数
生产环境别指望 --optimize-autoloader 加速 files 加载
--optimize-autoloader（或 -o）只影响 PSR-4/PSR-0 类映射，对 files 完全无感。它不会合并 helper 文件，也不会预编译函数——files 始终走独立 require_once 流程，且每次请求都执行。
真正影响性能的是你写的代码本身：
- 不要在 helper 文件里做耗时操作（如连接数据库、扫描目录、读大文件）
- 避免在其中调用
opcache_get_status()或其他运行时探测函数 - 如果 helper 只供 CLI 使用（如 Artisan 命令），考虑移到
autoload-dev块，并用composer install --no-dev排除，减少 Web 请求的加载开销
phpunit 自带的 vendor/autoload.php，而线上可能是 Nginx + PHP-FPM 直接跑入口脚本，两者是否都明确 require 'vendor/autoload.php'，决定了 helper 函数到底有没有机会被载入。
