PHP 源码调试入门：用 Xdebug 跟踪函数调用

程序运行结果不符合预期时，问题未必出在最后报错的那一行。一次请求可能经过路由、控制器、服务、数据库封装和多个回调；如果只看异常堆栈，往往只能看到出错时的调用关系，难以还原此前执行过哪些函数、参数如何传递、代码从哪里开始变慢。

Xdebug 的函数调用跟踪（function trace）会把一次执行过程中的函数进入、退出和相关信息写入文件，便于事后检查调用顺序、调用位置与耗时。它适合排查复杂调用链、观察难以复现的分支，以及初步定位性能热点。它不是通用性能分析器，也不能替代日志、单元测试或安全审计。本文以 PHP 8 和 Xdebug 3 为例，说明从配置到读日志的完整流程，并指出使用时容易忽略的边界。

一、函数跟踪能解决什么问题

函数跟踪最有用的地方，是把“程序刚才做了什么”变成一份可搜索的执行记录。例如：

• 排查调用链：确认某个服务方法是否被调用、调用了几次，以及调用顺序。
• 核对参数传递：在当前版本和配置支持的范围内，查看跟踪中记录的参数信息，辅助发现意外的空值或错误对象。
• 定位重复工作：发现循环中反复调用数据库封装、模板渲染或昂贵的业务函数。
• 辅助分析执行时间：查看函数耗时和执行期间的内存变化，寻找值得进一步测量的代码段。

跟踪记录的是特定一次执行。它不能证明其他请求、其他输入或并发场景也会走相同路径；记录中的耗时也受环境、机器负载、跟踪开销和输入数据影响。若问题只在少数请求中出现，应尽量只对可复现的请求开启跟踪，并保存必要的请求上下文。

二、安装并确认 Xdebug 已加载

Xdebug 是 PHP 扩展，需要安装到实际运行项目的 PHP 环境中。命令行 PHP、PHP-FPM 和 Apache 模块可能使用不同的 PHP 版本或配置文件，所以“命令行能用”不等于“网页请求也能用”。

先查看当前 PHP 的版本、配置文件和已加载模块：

php -v
php --ini
php -m | grep -i xdebug

Windows 用户可以使用 findstr 代替 grep：

php -m | findstr /i xdebug

如果没有看到 Xdebug，请按照对应操作系统、PHP 版本及安装方式配置扩展。Linux 上可通过系统包管理器或 PECL 安装；Windows 上需要与 PHP 版本、线程安全类型、架构匹配的扩展文件。容器环境则应在 PHP 容器中安装，而不是只在宿主机上安装。

安装后，重新启动使用该 PHP 的服务，再分别检查 CLI 和 Web 环境。网页端可临时通过受控的诊断脚本查看 phpinfo()，但要避免将包含环境信息的页面暴露到公网，并在确认配置后删除该脚本。

三、配置 Xdebug 3 的跟踪模式

Xdebug 3 使用 xdebug.mode 控制启用哪些功能。跟踪对应的模式是 trace。该设置需要在 PHP 启动时生效：仅在脚本运行过程中调用 ini_set()，不能把未启用的模式动态打开。因此，应在 PHP 配置文件、容器环境变量或启动命令中设置。

下面是一份用于本地诊断的示例配置。实际配置文件的位置以 php --ini 和 Web 环境的配置检查结果为准。

zend_extension=xdebug

xdebug.mode=trace
xdebug.start_with_request=trigger
xdebug.output_dir=/tmp/xdebug-traces
xdebug.trace_output_name=trace.%p.%t
xdebug.trace_format=0

如果扩展加载行已经由安装工具写入配置，不要重复添加。xdebug.output_dir 指定跟踪文件的输出目录；目录必须存在，且运行 PHP 的用户需要有写权限。示例中的 %p 和 %t 是文件名模板标记，分别用于加入进程标识和时间信息，减少文件名冲突。请根据需要阅读所用 Xdebug 版本的命名规则。

xdebug.trace_format=0 生成便于人工阅读的文本格式。Xdebug 也支持计算机可读格式；如果要用脚本处理数据，可以根据当前版本文档选择相应格式。不要默认所有版本和工具都支持同一种格式。

本例使用 xdebug.start_with_request=trigger，表示只有请求带有有效触发条件时才启动跟踪。Xdebug 3 可识别 XDEBUG_TRIGGER 触发值，触发入口可能是环境变量、Cookie 或请求参数，具体取决于执行环境和版本行为。不要假设任意名为 debug 的参数都会触发跟踪。

可以配置一个非空的触发值，避免仅凭简单参数就启动跟踪：

xdebug.trigger_value=local-trace-key

触发值并不是完整的身份认证或访问控制机制。它可能出现在浏览器记录、代理日志、应用日志或共享链接中，也可能被其他人获取。不要把 Xdebug 跟踪触发器当作公开网站上的安全开关；应配合内网访问、身份验证、防火墙或 VPN 等措施，并限制跟踪文件的访问权限。

修改配置后，应重启 PHP-FPM、Apache 或相关容器。CLI 配置通常在新进程启动时读取。再次执行 php -i，或在受控环境中查看 Web 侧的 Xdebug 配置，确认设置确实生效。Xdebug 的模块模式和触发行为若与预期不符，首先检查实际服务使用的配置文件，而不是盲目继续修改某个 php.ini。

四、用 CLI 触发一次跟踪

命令行程序可通过环境变量触发跟踪。以下命令以类 Unix shell 为例：

XDEBUG_TRIGGER=local-trace-key php demo.php

PowerShell 中可以这样设置环境变量并运行：

$env:XDEBUG_TRIGGER = "local-trace-key"
php .\demo.php
Remove-Item Env:XDEBUG_TRIGGER

如果没有设置 xdebug.trigger_value，触发器的具体校验行为会有所不同；为了让示例可控，建议在本地明确配置触发值，并保证命令中的值与配置一致。运行后检查 xdebug.output_dir 指向的目录，确认是否生成跟踪文件。文件名由 xdebug.trace_output_name 等设置决定，不要依赖某个固定文件名。

五、一个可运行的调用链示例

下面的脚本只使用 PHP 内置功能，可以保存为 demo.php 运行。它模拟控制器调用服务、服务整理订单并计算总价的过程：

<?php

declare(strict_types=1);

function formatOrder(array $items): array
{
    $result = [];

    foreach ($items as $item) {
        $result[] = [
            'name' => strtoupper($item['name']),
            'price' => (float) $item['price'],
            'quantity' => (int) $item['quantity'],
        ];
    }

    return $result;
}

function calculateTotal(array $items): float
{
    $total = 0.0;

    foreach ($items as $item) {
        $total += $item['price'] * $item['quantity'];
    }

    return $total;
}

function loadOrder(int $orderId): array
{
    $orders = [
        42 => [
            ['name' => 'book', 'price' => '12.50', 'quantity' => '2'],
            ['name' => 'pen', 'price' => '3.20', 'quantity' => '1'],
        ],
    ];

    return $orders[$orderId] ?? [];
}

function showOrder(int $orderId): void
{
    $rawItems = loadOrder($orderId);
    $items = formatOrder($rawItems);
    $total = calculateTotal($items);

    echo 'Order ' . $orderId . ' total: ' . number_format($total, 2) . PHP_EOL;
}

showOrder(42);

运行命令：

XDEBUG_TRIGGER=local-trace-key php demo.php

终端会输出订单总价，跟踪文件则保存到配置的输出目录。若结果文件不存在，可先直接检查扩展和模式：

php --ri xdebug

确认 CLI 中显示 Xdebug，并检查 xdebug.mode、xdebug.start_with_request、xdebug.output_dir 等值。还要检查目录权限、触发值是否一致，以及命令执行的 PHP 是否使用了预期配置。

六、如何阅读跟踪文件

文本格式跟踪通常会按执行顺序列出函数调用和退出，并附带深度、时间或内存等列。具体列名和呈现方式随 Xdebug 版本及跟踪格式而异。阅读时不必从头逐行理解，可以先围绕目标函数搜索，再向前后查看调用关系：

1. 先定位业务入口，例如 showOrder。
2. 查看它进入了哪些函数，以及调用深度如何变化。
3. 搜索可疑函数，确认它是否被重复调用，或是否出现在意料之外的分支中。
4. 观察时间信息，找出耗时较突出的调用，再用更有针对性的测量验证。

例如，在示例中应能观察到 showOrder 调用 loadOrder、formatOrder 和 calculateTotal。实际记录还可能包含 PHP 内部函数、框架代码、自动加载过程和扩展调用，因此文件往往比预期长。可以使用文本搜索、编辑器的折叠功能或脚本筛选，但应保留足够上下文，避免只看某一行就推断完整因果关系。

跟踪时间不等同于精确的独立函数基准。启用跟踪会带来额外开销，系统负载和 I/O 也会影响结果。若要量化性能改进，应使用可重复的测试输入、稳定的测试环境，并结合专业 profiler、基准测试或应用监控验证；不要仅凭一次跟踪中的数值给出绝对结论。

七、在代码中只跟踪一段逻辑

有时不想记录整个请求，可以在代码中通过 xdebug_start_trace() 和 xdebug_stop_trace() 划定范围。这两个函数要求 Xdebug 扩展已加载，并且跟踪模式已在启动时启用。以下示例应在与前文相同的触发配置下运行：

<?php

declare(strict_types=1);

if (!function_exists('xdebug_start_trace')) {
    throw new RuntimeException('Xdebug trace is not available.');
}

$traceFile = xdebug_start_trace();

if ($traceFile === false) {
    throw new RuntimeException('Could not start Xdebug trace.');
}

try {
    showOrder(42);
} finally {
    xdebug_stop_trace();
}

echo 'Trace saved to: ' . $traceFile . PHP_EOL;

可将该代码放在可访问 showOrder() 定义的脚本中。finally 能确保在正常异常流程中尝试停止跟踪，避免跟踪范围意外延长。实际项目中，若跟踪启动失败，常见原因包括模式未启用、输出目录不可写或配置与预期不符。

程序若被强制终止、进程崩溃或请求超时，脚本中的清理逻辑未必有机会运行，跟踪文件也可能不完整。不要将手动启停当成所有情况下都能保证文件完整的机制。生产排障前应先在相似环境验证，并评估请求生命周期、异常处理和文件空间。

八、Web 请求如何触发

对 PHP-FPM 或 Apache 处理的请求，应先确认 Web 服务实际加载了 Xdebug，并应用了 xdebug.mode=trace 和触发配置。CLI 与 Web 使用不同配置是常见情况。可以在本地浏览器请求中通过 Cookie 或受控请求参数传递触发值，也可以使用能设置请求头或 Cookie 的测试客户端；可用入口与传递方式应以当前 Xdebug 版本文档及 Web 环境为准。

触发一次请求后，检查输出目录是否生成新文件，并通过请求时间、文件名和业务日志对应起来。若应用有反向代理、容器或多台服务器，文件可能写在处理请求的容器或节点中，而不是你当前查看的机器上。容器重启后数据还可能消失，必要时使用受控的持久化目录，并限制其权限。

不要为了方便在生产环境长期设置 xdebug.start_with_request=yes。这会让请求持续生成跟踪数据，造成明显的 I/O、磁盘和性能负担，也会增加敏感信息落盘的风险。更稳妥的方式是在开发环境按需触发；确需在线排查时，应严格限制可触发人员、时间范围、采样范围和文件保留周期。

九、参数记录的边界与敏感信息

跟踪文件可能包含函数参数、路径、对象或其他执行信息，具体内容取决于 Xdebug 版本、跟踪格式和配置。参数记录有助于定位问题，但不能假定它会完整、无损地呈现所有复杂值，也不能假定所有版本的参数收集行为完全相同。Xdebug 2 的配置项与 Xdebug 3 的行为并非一一对应；升级时应查阅对应版本的迁移说明和配置文档，不要照搬旧教程中的参数设置。

即使某个跟踪文件没有完整显示对象内容，也不意味着其中不含敏感信息。参数可能包含密码、访问令牌、用户数据、文件路径、SQL 条件或支付相关字段；调用链和文件路径本身也可能泄露应用结构。跟踪文件应按敏感诊断资料处理：

• 将输出目录放在 Web 根目录之外，避免被浏览器直接下载。
• 限制文件及目录的读取权限，只授权必要的开发和运维人员。
• 不要把未经检查的跟踪文件提交到公开代码仓库或发送到不受控的工单系统。
• 排障完成后按保留策略删除文件；若必须留存，进行访问控制和安全传输。
• 避免在生产环境跟踪含有真实凭证或大量个人数据的请求。

触发值也不应被视为密钥系统。它只控制是否启动跟踪，并不能替代访问控制、加密、脱敏或审计。若敏感参数必须参与排障，可优先构造脱敏测试数据，或通过应用层日志只记录必要字段。

十、常见错误及排查顺序

1. CLI 能用，网页没有跟踪文件

检查 PHP-FPM、Apache 或容器实际使用的配置文件和扩展版本，确认服务已重启。CLI 的 php --ini 只说明命令行 PHP 的配置，不代表 Web 环境。

2. Xdebug 已加载，但没有输出

检查 xdebug.mode 是否包含 trace，启动方式是否设置为 trigger，请求是否确实携带了有效触发值。Xdebug 3 的模式需要在 PHP 启动时确定；运行脚本后调用 ini_set() 不能补开跟踪模式。

3. 跟踪文件无法创建

检查输出目录是否存在、PHP 运行用户是否具有写权限，以及容器文件系统是否允许写入。还应查看磁盘空间和 PHP 服务错误日志。避免使用权限过宽的方式“解决”写入问题，例如把目录开放给所有用户读写。

4. 文件特别大，服务器变慢

跟踪会记录大量执行事件，框架启动、自动加载和循环调用都可能迅速扩大文件。缩小跟踪范围、缩短运行时间、使用触发模式，并设置合理的清理策略。不要在高流量环境无差别启用全请求跟踪。

5. 找不到预期的参数内容

先确认跟踪格式和 Xdebug 版本，再查看该版本对参数记录的说明。不同版本和格式的表现可能不同；也要考虑值是否被截断、以摘要形式显示，或本身不适合按普通文本阅读。不要因为某个值未出现在文件中，就断定函数没有收到它。

6. 触发参数看起来正确，却没有启动

确认使用的是 Xdebug 识别的触发入口和变量名，并核对 xdebug.trigger_value 是否与请求中的值一致。浏览器、代理和应用可能会过滤或重写 Cookie、查询参数或请求头；可以在受控环境中检查 PHP 实际收到的请求数据，但不要把触发值写入公开日志。

十一、什么时候不该只靠函数跟踪

如果问题是偶发线上错误，应用日志、错误监控和分布式追踪通常更适合提供跨请求、跨服务的背景；函数跟踪对单个 PHP 进程的执行过程观察更细，但文件体积大、开销高，也难以直接展示请求之间的关联。

如果目标是系统性分析性能，应使用性能分析器生成调用树或采样数据，并配合数据库查询分析和应用指标。函数跟踪更适合回答“这一次执行实际调用了什么”，不适合单独回答“在所有流量中哪段代码最耗资源”。若要排查业务逻辑，应优先增加有意义的应用日志或测试断言，避免把海量底层调用记录当成业务事实。

总结

使用 Xdebug 跟踪函数调用，可以按以下顺序操作：确认目标 PHP 环境加载了 Xdebug；在启动配置中启用 trace 模式；将跟踪输出到 Web 根目录之外且可写的目录；优先使用触发模式；对一次可复现的执行生成文件；从入口和可疑函数开始阅读，并用其他测量手段验证性能判断。

最重要的边界也要记住：CLI 和 Web 配置可能不同；Xdebug 模式不能靠脚本运行时临时开启；跟踪会增加开销并可能写入敏感参数；触发值不是完整安全措施；跟踪耗时不能直接当作精准基准。把跟踪限定在需要的请求和时间范围内，并妥善保护、清理文件，才能让它成为有效的调试工具，而不是新的数据风险和性能负担。