如何在ubuntu上调试thinkphp代码

在 Ubuntu 上调试 ThinkPHP 的高效流程

一 环境准备与快速验证

• 安装基础环境（以 PHP 7.4/8.x 为例）：
  • sudo apt update
  • sudo apt install php php-cli php-fpm php-mysql php-curl php-gd php-mbstring php-xml php-zip
• 安装 Nginx 或 Apache（二选一），并启动服务；Nginx 示例：
  • sudo apt install nginx
  • sudo systemctl start nginx && sudo systemctl enable nginx
• 安装 Composer 并创建项目（以 ThinkPHP 6 为例）：
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer
  • composer create-project topthink tp
• 配置 Web 服务器指向入口 public/index.php，Nginx 示例：
  • root /var/www/html/tp/public; index index.php;
  • location / { try_files $uri $uri/ /index.php?$query_string; }
  • location ~ .php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; }
• 访问 http://your_domain_or_ip 验证是否出现欢迎页。

二 开启框架内置调试与日志

• 开启调试模式：在应用配置中将 app_debug 设为 true（如 config/app.php 或 .env 对应项），可输出更详细的错误与调用栈信息。
• 查看日志：框架运行期错误与调试信息会写入 runtime/log 目录，白屏或无输出时优先检查该目录日志文件。
• 页面 Trace：开发阶段可开启 页面 Trace（如配置文件增加 ‘SHOW_PAGE_TRACE’ => true），便于查看请求、SQL、用时等信息。
• 变量与性能辅助：
  • 使用框架提供的 dump($var) 打印复杂变量（比 var_dump 更友好）。
  • 使用 debug_start(‘label’) / debug_end(‘label’) 统计代码段执行时间与内存。
  • 使用模型的 getLastSql() 快速查看最近一次执行的 SQL，定位查询问题。

三 使用 Xdebug 进行断点调试（PHPStorm 示例）

• 安装 Xdebug（Ubuntu 常见做法）：
  • sudo apt install php-xdebug
  • 或在 php.ini 中配置 zend_extension=xdebug.so（路径以 phpinfo() 为准）
• 配置 php.ini（Xdebug 3 常用写法，端口示例 9003）：
  • [xdebug]
  • zend_extension=xdebug.so
  • xdebug.mode=debug
  • xdebug.start_with_request=yes
  • xdebug.client_host=127.0.0.1
  • xdebug.client_port=9003
  • xdebug.log=/var/log/php/xdebug.log
• PHPStorm 设置：
  • Settings → PHP → Debug：确认 Debug port 为 9003
  • Run → Edit Configurations → PHP Remote Debug：新建配置，设置服务器与本机 IP/端口，勾选 “Break at first line in PHP scripts”
• 开始调试：
  • 在 IDE 中开启监听（Start Listening for PHP Debug Connections）
  • 浏览器访问目标 URL（可带 XDEBUG_SESSION_START=PHPSTORM 触发调试）
  • 命中断点后可查看变量、调用栈、单步执行等。

四 常见问题与排查要点

• 404 或控制器/方法不存在：核对 URL 路由 与控制器命名空间、方法是否存在，必要时查看路由定义与伪静态规则。
• 数据库连接失败：检查 .env / 数据库配置（主机、库名、账号、密码、端口）与数据库服务状态、访问权限。
• 白屏或空白页：优先查看 runtime/log 日志与 PHP 错误日志（如 /var/log/php/*），常见为语法错误、权限不足或配置错误。
• SQL 问题定位：开启 SQL 日志 或使用 getLastSql() 复核最终执行的 SQL 与绑定参数。
• Xdebug 连不上：
  • 核对 client_host/client_port 与 IDE 监听端口一致（常见 9003）
  • 确认 Web 与 IDE 在同一网络或正确可达
  • 检查 xdebug.log 输出与防火墙设置。