ThinkPHP 6/8 调试模式生效需在入口文件最顶部定义 APP_DEBUG 常量，否则 Trace、SQL 日志、异常堆栈均静默失效；常见错误包括 .env 或 config 中设置无效、Trace 图标不显示、日志无记录。
APP_DEBUG常量没在入口文件最顶部定义
ThinkPHP 6/8 的调试模式是否生效，只认 APP_DEBUG 这个常量，而且必须在框架加载前就存在。如果写在 require 'thinkphp/base.php' 或 require vendor/autoload.php 之后，整个调试链路（Trace、SQL 日志、异常堆栈）都会静默失效。
常见错误现象：
- 改了 .env 里的 APP_DEBUG=true，页面还是“页面错误，请稍后再试~”
- config/app.php 中写了 'app_debug' => true，但没反应
- Trace 小图标不出现，runtime/log/ 里也没新日志
实操建议：
- 打开 public/index.php，删掉所有前置内容，确保第一行是：<?php define('APP_DEBUG', true);ini_set('display_errors', '1');error_reporting(E_ALL);
- 紧接着才是 require 相关语句
- 删掉整个 runtime/ 目录（含子目录），否则旧缓存会干扰新配置
.env 文件未被正确加载或格式错误
.env 只在 APP_DEBUG 未被显式定义时才起作用，且加载时机非常早——仅在应用初始化早期自动读取一次，路径固定为项目根目录（与 public/ 同级），不会自动找 .env.local 或带 BOM 的文件。
常见错误现象：
- .env 写了 APP_DEBUG=true 却没效果
- 用编辑器另存为 UTF-8 with BOM，导致 App::loadEnv() 解析失败
- 等号两侧有空格，如 APP_DEBUG = true，会被忽略
- APP_ENV=prod 覆盖了 APP_DEBUG=true（TP6.1+ 行为）
实操建议：
- 确保 .env 在项目根目录，编码为 UTF-8 无 BOM
- 写成严格格式：APP_DEBUG=true、APP_ENV=dev、APP_TRACE=true
- 不要依赖 putenv() 或中间件里重载 —— 它不是运行时配置源
- 修改后必须重启 Web 服务或 CLI 进程（Swoole 尤其要注意）
PHP 层错误显示被全局屏蔽
即使 APP_DEBUG=true，若 PHP 自身禁用了错误输出，框架也渲染不出调试页面。Nginx + PHP-FPM 架构下，php_admin_flag[display_errors] 可能直接覆盖代码级设置；而 vendor/autoload.php 加载失败这类底层错误，连框架初始化都进不去，ini_set() 根本无效。
实操建议：
- 入口文件顶部加三行强制开启：error_reporting(E_ALL);ini_set('display_errors', '1');ini_set('display_startup_errors', '1');
- 若仍白屏，检查 php.ini：确认 display_errors = On 和 error_reporting = E_ALL
- Nginx 下检查 PHP-FPM 池配置，添加：php_admin_flag[display_errors] = on
- 验证是否真有解析错误：临时删掉 public/index.php 最后一行，看是否报 Parse error
配置缓存或 OPCache 导致“假失效”
ThinkPHP 8 默认在 app_debug = false 时生成 runtime/config.php，该文件一旦存在且语法合法，框架就会跳过重新读取 config/app.php 和 .env。OPCache 更会把旧的 config/app.php 编译结果锁死，改了文件也不生效。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- 运行 php think config:clear 清除所有配置缓存
- 手动删掉 runtime/config.php 和 runtime/config/ 子目录
- 执行 opcache_reset() 或重启 PHP-FPM（CLI 下可加 php -d opcache.enable=0 临时绕过）
- 验证是否生效：在控制器中写 var_dump(config('app.app_debug'));，输出必须是 bool(true)
真正卡住排查的，往往不是配置写错了，而是错误发生在框架加载前（比如入口文件语法错、扩展缺失）、或者 runtime/ 目录权限不对、又或者 Docker 容器里挂载的路径没映射写权限。
