ThinkPHP5调试模式仅由入口文件index.php首行define('APP_DEBUG', true)决定，必须紧贴<?php后、清空runtime目录、配合display_errors开启才能生效，.env和config.php中的配置均不参与开关逻辑。
ThinkPHP5 调试模式只认入口文件顶部的 APP_DEBUG 常量，其他任何地方改都无效——哪怕你改了 config.php 里的 app_debug，只要入口没定义或定义位置错了，就看不到错误堆栈和 Trace 面板。
入口文件必须第一行就写 define('APP_DEBUG', true)
TP5 的入口文件是项目根目录下的 index.php（不是 public/index.php），它在加载框架前就检查 APP_DEBUG。这行代码必须紧贴 <?php 后面，前面不能有空行、BOM、注释或输出。
- ✅ 正确位置：
<?php define('APP_DEBUG', true); require __DIR__ . '/thinkphp/start.php'; - ❌ 错误写法：放在
require之后、用字符串'true'或数字1、或者写成app_debug（大小写敏感） - 删掉
runtime/目录全部内容（含子目录和隐藏文件），否则旧缓存会掩盖新配置 - 刷新页面后右下角出现灰色 Trace 图标，或访问不存在控制器时显示完整
ClassNotFoundException堆栈，说明生效
.env 文件在 TP5 中仅作后备，且容易被忽略细节
TP5 支持 .env，但它只在入口文件**未定义** APP_DEBUG 时才读取。很多人改了 .env 却没反应，就是因为入口文件里还留着旧的 define。
- 确保项目根目录有
.env（无 BOM，UTF-8 编码），内容严格为：APP_DEBUG=true
- 等号两侧不能有空格，否则框架解析失败
- 如果入口文件中仍有
define('APP_DEBUG', ...)，.env的值会被完全忽略 - 改完必须清空
runtime/，否则缓存可能沿用上一次的判断结果
为什么开了 APP_DEBUG 还是白屏或 500？
TP5 不会自己打开 PHP 底层错误输出。即使 APP_DEBUG = true，若 display_errors 关闭，页面依然空白。
立即学习“PHP免费学习笔记（深入）”；
- 在
index.php顶部、define('APP_DEBUG', true)后立刻加：ini_set('display_errors', '1'); - 检查
php.ini中error_reporting是否设为E_ALL（TP5 默认依赖这个） - 如果你用 Nginx + PHP-FPM，确认
fastcgi_intercept_errors off;，否则 Nginx 会吞掉 ThinkPHP 渲染的错误页 - 自定义了异常处理器？确保继承
\think\exception\Handle并调用了parent::render($e)，否则堆栈不会输出
config.php 里的 app_debug 是个“摆设”
TP5 的 application/config.php 中确实有 'app_debug' => true 这项，但它只是供运行时读取的只读状态，不参与调试模式开关逻辑。它甚至不会影响模板重编译或 SQL 日志是否启用。
- 这个配置项只在
APP_DEBUG === true时被框架读取，单独设为true完全无效 - 它常被误认为是开关，实际只是“调试已开启”后的副产品，比如用于视图中判断：
{if \think\App::debug()}... - 如果你发现改了这里就有变化，大概率是入口文件漏清缓存，导致旧
APP_DEBUG值还在 runtime 里残留
真正卡住人的从来不是“怎么写”，而是“谁先执行、谁覆盖谁、谁没清缓存”。TP5 的 APP_DEBUG 是硬编码级开关，一旦错过入口文件那几行，后面所有配置都只是幻觉。
