赞片CMSdebug模式

学完这篇，你能在赞片CMS里正确开启和关闭 debug 模式，并用页面 Trace 和运行日志定位白屏、模板不更新、SQL 报错等常见问题。下面以赞片CMS v2.3（ThinkPHP 3.2 内核）为例，步骤对其他 v2.x 版本基本通用。

第一步：确认版本并备份

先确认你用的是哪个版本，避免参数写错。登录赞片CMS后台，看首页右下角或“系统 -> 系统信息”里的版本号；也可以打开 /Application/Common/Conf/version.php 查看。确认后，把网站根目录整体打包备份一份，尤其是 /Application/Common/Conf/config.php 和根目录 /index.php。debug 模式会改变程序行为，出问题时能立刻还原。

第二步：打开入口文件的调试开关

这一步要开启 ThinkPHP 的调试模式，做完后页面报错会显示详细堆栈，而不是只给一个白屏。用编辑器打开网站根目录的 /index.php，找到这一行：

define('APP_DEBUG', false);

改成：

define('APP_DEBUG', true);

如果文件里没有这行，就在 require './ThinkPHP/ThinkPHP.php'; 之前手动加一行 define('APP_DEBUG', true);。保存后刷新网站，如果代码有语法错误，页面会直接显示错误文件和行号。

注意：APP_DEBUG 为 true 时，ThinkPHP 不会缓存编译文件，页面会变慢，这是正常现象。

第三步：打开页面 Trace 和日志记录

这一步让页面右下角出现调试面板，同时把 SQL、错误写入日志。打开 /Application/Common/Conf/config.php，加入或修改以下配置：

'SHOW_PAGE_TRACE' => true,
'LOG_RECORD' => true,
'LOG_LEVEL' => 'EMERG,ALERT,CRIT,ERR,SQL,DEBUG,INFO',
'TMPL_CACHE_ON' => false,
'HTML_CACHE_ON' => false,

SHOW_PAGE_TRACE 控制右下角调试按钮，LOG_RECORD 开启日志，LOG_LEVEL 里的 SQL 会记录每条 SQL。TMPL_CACHE_ON 和 HTML_CACHE_ON 设为 false 后，改模板和改 HTML 规则不用反复清缓存。

第四步：清理旧缓存

改完配置后必须清缓存，否则旧配置和旧模板仍然生效。手动删除 /Runtime/Cache/ 和 /Runtime/Data/ 下的所有文件；如果后台能进，再走一遍“系统 -> 缓存管理 -> 清除缓存”（部分版本叫“更新缓存”）。删除后刷新前台，右下角会出现 ThinkPHP 的 Trace 小图标。

第五步：用 Trace 和日志排查问题

点开右下角 Trace，重点看三个标签：SQL 看执行了哪些语句、有没有重复查询；错误 看有没有 Warning 和 Notice；运行时间 看哪一段耗时突然变高。日志文件在 /Runtime/Logs/Home/ 或 /Runtime/Logs/Admin/ 下，按日期命名，例如 2024-06-01.log。如果前台白屏但 Trace 不出现，直接看当天的日志文件，通常最后一行就是致命错误原因。

注意：如果日志目录没有写入权限，日志会写不进去。Linux 下给 /Runtime 目录 755 或 777 权限，Windows 下检查是否被安全软件拦截。

第六步：调试完必须关闭

问题解决后，把 /index.php 里的 APP_DEBUG 改回 false，把 config.php 里的 SHOW_PAGE_TRACE 改回 false、LOG_RECORD 改回 false，并恢复 TMPL_CACHE_ON 和 HTML_CACHE_ON 为 true。最后删除 /Runtime/Logs/ 下的日志文件，再清一次缓存。生产环境长期开着 debug，会暴露数据库账号、文件路径和 SQL 结构，极易被扫描利用。

小结

• debug 模式核心是入口文件 APP_DEBUG 设为 true。
• 页面 Trace 和 SQL 日志靠 config.php 里的 SHOW_PAGE_TRACE、LOG_RECORD、LOG_LEVEL 控制。
• 改模板不生效时，关掉 TMPL_CACHE_ON 和 HTML_CACHE_ON 并清 /Runtime。
• 日志位置在 /Runtime/Logs/模块名/日期.log。
• 调试完必须关闭所有开关并删除日志，避免安全风险。