trae 是第三方 CLI 工具，其 auto_prepend_file_trae 是自定义配置项，不依赖 PHP 的 auto_prepend_file；它在每次 HTTP 请求前 require 指定文件，仅对 trae serve 有效，路径须为项目根目录下的可读 PHP 文件。
trae 是什么，和 PHP 的 auto_prepend_file 有关系吗
trae 不是 PHP 官方机制，也不是 Apache/Nginx 内置功能，而是 trae 这个第三方 CLI 工具（常用于本地 PHP 开发环境快速启服务）自己实现的“自动前置包含”逻辑。它**不依赖 PHP 配置项 auto_prepend_file**，也不修改 php.ini 或 .htaccess。你看到的 auto_prepend_file_trae 是 trae 自己定义的配置键，仅在它的配置文件（如 trae.json）中生效。
在 trae.json 中正确设置 auto_prepend_file_trae
trae 通过 JSON 配置驱动行为，auto_prepend_file_trae 必须写在根级或 server 对象下，且值必须是相对于项目根目录的**可读 PHP 文件路径**（不能是 URL，不能用 ~ 或环境变量）：
{
"auto_prepend_file_trae": "bootstrap.php",
"server": {
"host": "localhost",
"port": 8080
}
}
-
bootstrap.php必须存在，且不能有语法错误——trae 启动时会立即 require 它，出错则直接退出并报PHP Parse error - 路径不支持通配符或数组，只接受单个字符串；若需多个文件，应在
bootstrap.php内部自行require - 该文件在每次 HTTP 请求开始前被 include（类似
auto_prepend_file），但**不作用于 CLI 命令本身**（比如trae serve执行时不运行它）
为什么设置了没生效？常见断点排查
trae 的自动包含容易因路径、权限或启动方式失效，重点检查这几处：
- 确认你运行的是
trae serve（不是php -S或其他服务器），只有serve子命令才读取auto_prepend_file_trae - 检查当前工作目录是否为含
trae.json的项目根目录——trae 不会向上查找配置文件 - 用
trae --debug serve启动，看控制台是否输出Prepending file: /full/path/to/bootstrap.php；没输出说明配置未加载 -
bootstrap.php中加一行file_put_contents('/tmp/trae-prepend.log', date('c') . "\n", FILE_APPEND);，请求后检查日志是否生成，可验证是否真被包含
和原生 auto_prepend_file 的关键差异
别把 trae 的行为当成 PHP 核心功能来调试。它本质是 trae 在内部封装了 require 调用，因此：
立即学习“PHP免费学习笔记（深入）”；
- 不继承 php.ini 的
open_basedir限制（trae 进程本身有读取权限即可） - 无法通过
ini_set('auto_prepend_file', ...)动态修改——这个 ini 设置对 trae 无效 - 如果同时配置了 php.ini 的
auto_prepend_file和 trae 的auto_prepend_file_trae，两者会**先后执行**，顺序是：php.ini 的先运行，trae 的后运行 - 不支持
.user.ini方式覆盖，trae 只认自己的 JSON 配置
真正难搞的往往是 bootstrap.php 里用了尚未初始化的全局变量，或者依赖了还没加载的 autoloader——这些错误不会报在 trae 启动阶段，而是在第一个请求时崩，得盯住 Web 服务器日志而非终端输出。
