ThinkPHP 调试模式必须在入口文件顶部用 define('APP_DEBUG', true) 硬编码开启，且位置严格、类型严格（布尔true），否则无效；同时需确保PHP错误输出开启、清除runtime缓存、正确配置APP_TRACE等子开关。
ThinkPHP 调试模式不会自动生效，必须在入口文件顶部用 define('APP_DEBUG', true) 硬编码开启，且该行必须出现在任何 require 或框架加载语句之前——否则白写。
入口文件顶部必须定义 APP_DEBUG 常量
这是唯一被所有 ThinkPHP 版本（5.x/6.x/8.x）无条件识别的开关方式。框架在加载早期就检查这个常量，错过时机就彻底失效。
-
APP_DEBUG不是配置项，不是函数，也不是环境变量别名；它就是一个 PHP 常量，且只认这一个名字 - 位置必须严格：public/index.php（TP6/8）或 index.php（TP5）最顶部，
<?php后第一行或第二行，不能有任何require、include、use或输出 - 写成
define('APP_DEBUG', 'true')（字符串）或define('APP_DEBUG', 1)都无效，必须是布尔true - 如果用了多入口（如 admin.php、api.php），每个都要单独加这一行
为什么开了 APP_DEBUG 还是白屏或 500？
ThinkPHP 的调试页面依赖 PHP 底层错误输出能力。即使 APP_DEBUG = true，若 PHP 自身屏蔽了错误，你照样看不到堆栈。
- 在入口文件中
define('APP_DEBUG', true)后立即加：ini_set('display_errors', '1');和error_reporting(E_ALL); - Nginx + PHP-FPM 环境下，检查 fastcgi_params 是否含
fastcgi_intercept_errors on;—— 必须设为off，否则 Nginx 会吞掉 PHP 错误页 - Docker 或共享主机常见问题：镜像默认关了
display_errors，光改代码没用，得进容器改php.ini或启动时注入 - CLI 场景（如
php think route:list）需额外加-v参数才显示完整异常，不加则静默失败
.env 文件里的 APP_DEBUG=true 为什么有时不生效？
.env 是后备方案，优先级低于代码中 define()。一旦你在入口文件写了 define('APP_DEBUG', ...)，.env 里无论写什么都无效。
立即学习“PHP免费学习笔记（深入）”；
- 常见陷阱：开发时在 .env 设了
APP_DEBUG=true，上线又加了define('APP_DEBUG', false)，结果测试环境还显示调试面板——大概率是 runtime 缓存没清干净 - 确认 .env 文件编码为 UTF-8 无 BOM，等号两侧不能有空格，否则框架读不到
- TP6+ 中，
APP_TRACE=true才能启用右下角 Trace 面板，仅APP_DEBUG=true不够 - 清缓存不是可选项：删掉整个
runtime/目录（包括子目录和~runtime.php），否则旧配置可能被缓存沿用
调试模式开启后仍看不到 SQL 或变量信息？
TP6/8 把调试功能拆得更细，APP_DEBUG=true 只是总开关，具体能力要单独开。
- SQL 日志需确保
config/database.php中'debug' => true，且日志驱动未被覆盖 - 页面底部 Trace 面板需要
APP_TRACE=true（.env）或'show_debug' => true（config/app.php，仅当 APP_DEBUG 为 true 时才读取） - TP6 默认关闭
debug_show_exception，必须在config/app.php显式设为true才显示详细异常页 - 模板编译错误、路由未定义等底层问题，可能绕过 ThinkPHP 异常处理器，此时要查 PHP 错误日志（路径见
phpinfo()的error_log行）
真正卡住人的地方，从来不是“怎么写那行 define”，而是“谁在哪儿悄悄把它覆盖了”——比如入口文件、.env、Dockerfile、Nginx 配置、甚至 CI 流水线脚本里都可能藏着 APP_DEBUG=false。验证时别只看 config/app.php，直接在控制器里 var_dump(defined('APP_DEBUG') && APP_DEBUG);，结果必须是 bool(true) 才算真正落地。
