ThinkPHP 项目放到 Debian 上之后，很多问题并不是代码本身难查，而是排查入口选错了：页面报错该看调试模式，逻辑跑偏该用 Xdebug，访问异常往往还得回到 Nginx、Apache 或 PHP-FPM。下面按实际排错顺序，把 ThinkPHP 在 Debian 环境里最常用的几种调试方式拆开说明，方便你根据故障现象快速选方法。
先开启调试模式，拿到第一手报错信息
如果项目已经能跑起来，但页面显示异常、报 500 或逻辑直接中断，第一步通常不是到处加日志，而是先把 ThinkPHP 的调试模式打开。这样可以直接看到错误堆栈、文件路径、行号，以及数据库连接失败、语法错误等具体信息。
通过配置文件开启
找到项目根目录下的 config/app.php，部分版本可能是 config.php，把 'app_debug' 改成 true：
'app_debug' => true,通过 .env 开启并区分环境
如果你希望开发、测试、生产环境分开控制，直接改 .env 更合适，而且这类方式通常优先级更高。在项目根目录新增或修改：
APP_DEBUG=true开启后，页面会直接输出完整错误堆栈。对于“为什么这个请求直接挂了”这类问题，这是最快的第一步。
页面能打开时，优先用 ThinkPHP 内置调试工具
当项目不是完全不可用，而是变量值不对、某段逻辑结果异常、页面变慢时，ThinkPHP 自带的调试能力往往已经够用，不必一开始就上复杂工具。
用 dump() 看变量实际内容
最直接的方式是输出变量，确认参数、模型结果或中间数据是否符合预期：
dump($variable, true, '标签', true)这里第一个参数是目标变量；第二个参数设为 true 时表示返回内容而不是直接输出；第三个参数可作为标记标签；第四个参数设为 true 时会显示数据类型。查数组结构、对象属性或请求参数时很实用。
用 debug_start() 和 debug_end() 查耗时与内存
如果你怀疑慢查询、循环或某段业务逻辑拖慢了请求，可以在代码前后加上：
debug_start('label')
debug_end('label')这一组方法可以记录指定代码段的执行时间和内存占用。比如把数据库查询、外部接口调用、复杂计算分别包起来，性能瓶颈通常很快就能定位出来。
打开 Trace 信息看请求全链路
如果你想一次看到请求参数、执行 SQL、加载文件等信息，可以在配置里开启：
'SHOW_PAGE_TRACE' => true开启后，页面底部会出现 Trace 信息栏。对于路由走向不清晰、SQL 执行数量异常、文件加载过多这类问题，它比单点输出更适合做整体观察。
复杂逻辑或断点排查，直接接入 Xdebug
当问题已经不是“哪里报错”，而是“为什么代码会走到这里”“某个变量是在哪一步被改掉的”，就该用 Xdebug 做断点调试。它适合配合 PhpStorm 这类 IDE 使用，能查看调用栈、变量实时值，并支持单步执行。
先在 Debian 中安装 Xdebug
在终端执行：
sudo apt install php-xdebug如果你使用的是特定 PHP 版本，需要改成对应包名，比如 PHP 7.4 可使用 php7.4-xdebug。
在 php.ini 中写入调试配置
根据运行方式编辑对应配置文件：
- PHP-FPM：
/etc/php/{version}/fpm/php.ini - CLI：
/etc/php/{version}/cli/php.ini
加入以下配置：
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9003
# 注意：PHP 8+默认端口是9003
xdebug.remote_autostart=1
xdebug.idekey=PHPSTORM # 这个要和IDE里的设置对上在 PhpStorm 中完成映射和远程调试设置
以 PhpStorm 为例，进入 Settings > PHP > Servers，新增服务器，主机填写 127.0.0.1，端口填写 80 或 443，并勾选“Use path mappings”，把本地项目目录映射到服务器目录。
然后进入 Run > Edit Configurations，添加“PHP Remote Debug”配置，并选择刚才创建的服务器。配置完成后，就可以设置断点、单步执行，并实时查看变量值。涉及条件分支、依赖注入、模型调用链较长的场景，Xdebug 往往比日志更有效。
页面外的问题，靠日志和命令行补齐现场
有些问题不会直观显示在页面里，比如缓存没有刷新、日志没有写入、路由和控制器执行过程异常，或者某些逻辑只在服务器环境里触发。这时需要把 ThinkPHP 日志、CLI 调试和 Web 服务器日志结合起来看。
先把 ThinkPHP 日志级别配全
在 config/log.php 中设置：
'level' => ['error', 'sql', 'debug']或者在 .env 中写入：
LOG_LEVEL=error,sql,debug这样错误、SQL 和调试信息都会被记录下来，适合回看请求过程和数据库行为。
关键业务可以手动写自定义日志
对于订单状态流转、第三方接口返回值、条件分支命中情况这类信息，手动记录往往更清晰：
thinkLog::record('自定义日志信息', 'debug')这类日志尤其适合查“代码没报错，但结果不对”的问题。
用 tail -f 实时盯日志输出
ThinkPHP 日志默认位于 runtime/log，例如：
runtime/log/202509/25.log在 Debian 终端中可以直接执行：
tail -f runtime/log/202509/25.log这样发起请求时，最新日志会实时滚动出来，比反复刷新文件更高效。
命令行调试适合查路由、缓存和交互逻辑
在项目根目录下，ThinkPHP 可以直接通过命令行跑起来：
php think run这是 ThinkPHP 6+ 的方式；旧版本则可以使用：
php -S localhost:8000 -t public运行后，终端通常会输出路由匹配、控制器执行和 SQL 相关信息，适合查“请求有没有走到目标控制器”。
另外，几个常用命令也很实用：
php think clear
php think optimize:autoload
php think tinkerphp think clear 可用于清缓存，排查配置不生效；php think optimize:autoload 常用于处理类找不到的问题；php think tinker 则适合直接在交互式环境里测试模型和数据库查询。
访问异常时回头看 Nginx 或 Apache 日志
如果项目根本无法访问，或者出现 502、404 等问题，问题往往不在 ThinkPHP 本身，而在 Web 服务器或 PHP-FPM。
Nginx 错误日志路径通常是：
/var/log/nginx/error.log实时查看：
tail -f /var/log/nginx/error.log常见问题包括 PHP-FPM 未启动、fastcgi_pass 配置错误等。
Apache 错误日志路径通常是：
/var/log/apache2/error.log查看方式同样是：
tail -f /var/log/apache2/error.log像 mod_rewrite 未启用、目录权限不对等问题，通常都能在这里找到线索。
上线前别忘了关闭调试并检查权限
调试手段用得越全，越要注意开发环境和生产环境分离。尤其是 Debian 服务器直接对外提供服务时，错误堆栈、路径和配置暴露都会带来风险。
生产环境必须关闭调试
上线前要把 APP_DEBUG 设为 false，避免页面直接暴露数据库密码、项目路径等敏感信息。同时建议限制 .env 文件权限：
chmod 600 .env检查项目目录权限是否正确
如果日志写不进去、缓存目录不可写、上传文件失败，很多时候就是权限问题。常见处理方式如下：
sudo chown -R www-data:www-data /path/to/project
sudo chmod -R 755 /path/to/project把这一层确认好，能避免很多“代码看起来没问题，但服务就是不正常”的排查时间浪费。
一套更实用的 Debian 下 ThinkPHP 排查顺序
实际操作里，可以按这样一条线来处理：先开 APP_DEBUG=true 看页面报错；页面能打开但结果不对，就用 dump()、Trace 和性能分析；逻辑复杂时切到 Xdebug；如果请求压根没跑通，再去看 ThinkPHP 日志、命令行输出，以及 Nginx 或 Apache 的错误日志。
这套方法的重点，不是把所有工具一次开满，而是根据问题所在的层级逐步缩小范围。这样在 Debian 上调试 ThinkPHP，效率通常会比盲目翻代码高得多。
