唯一安全可维护的方式是用 autoload.files 列表引入单文件配置，因其不依赖类名路径映射，避免 psr-4 因无命名空间导致的 class not found 或 autoload 失效问题。
直接用 autoload.files 列表引入，别碰 PSR-4 或 classmap —— 这是唯一安全、可维护的方式。
为什么不能用 PSR-4 加载单文件配置？
PSR-4 要求类名与文件路径严格对应命名空间，而单文件（比如 config/database.php）通常没类、没命名空间，甚至只是纯数组或 return 语句。强行塞进 PSR-4 会导致：Class not found 报错，或 autoload 映射生成无效条目，后续 composer dump-autoload 可能静默失败。
怎么正确配置 autoload.files？
在 composer.json 的 autoload 段里声明 files 数组，每个元素是相对于项目根目录的 PHP 文件路径：
{
"autoload": {
"files": [
"config/database.php",
"config/app.php",
"framework/helpers.php"
]
}
}
- 路径必须是字符串，不能带变量或常量（如
__DIR__），因为 Composer 解析时还没执行 PHP - 文件必须以
.php结尾，且顶层不能有return以外的输出（避免 headers already sent） - 这些文件会在每次
require vendor/autoload.php时自动执行（不是延迟加载），适合放配置、函数定义、常量声明
执行 dump-autoload 后仍不生效？检查这三点
composer dump-autoload 必须运行，否则新 files 条目不会写入 vendor/composer/autoload_files.php。常见卡点：
- 忘记运行命令：改完
composer.json后直接测代码，结果文件根本没加载 - 路径写错：比如写成
"configs/database.php"，但实际是config/（少个i），错误不会报在 dump 阶段，而是在运行时提示failed to open stream - 入口文件漏掉
require 'vendor/autoload.php'：这是所有 autoload 规则的起点，跳过它等于整个 autoload 链断开
旧项目已有手动 require，怎么平滑过渡？
别删原有 require，而是把它们逐个挪进 autoload.files，再删掉原代码里的 require 行。例如：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
原来这样写：
require __DIR__ . '/config/database.php'; require __DIR__ . '/config/app.php';
改成：
{
"autoload": {
"files": ["config/database.php", "config/app.php"]
}
}
然后运行 composer dump-autoload，再删掉那两行 require。这样做既保留加载顺序，又把控制权交给 Composer，后续加新配置文件只需改 JSON，不用动 PHP 代码。
容易被忽略的是：这些文件一旦加入 autoload.files，就**永远在 autoload 链里执行**，没有条件判断余地。如果某配置只该在 CLI 下加载，就得在文件内部加 if (PHP_SAPI === 'cli') { ... }，而不是试图在 composer.json 里做环境分支。
