一、启动 Trailhead Playground
本动手项目用 VS Code + Salesforce Extensions 搭建 Apex 开发环境，创建带故意 bug 的 Apex 项目，用 Apex Replay Debugger 查找并修复 bug。与需要实时连接的 Interactive Debugger 不同，Replay Debugger 基于下载的调试日志工作——适合异步调试和团队协作。
项目概览与学习目标
本项目你将学会：设置断点（breakpoints）和检查点（checkpoints）逐步执行代码、在特定行检查变量值；用 VS Code 调用 Apex 测试并下载调试日志；用 Apex Replay Debugger 查找并修复一个 bug。
引言：调试 vs 测试
「任何在设计阶段未发现的 bug，在编码阶段发现的成本高 10 倍，在调试阶段又高 10 倍。」——Dr. Nikolai Bezroukov。测试（testing）尝试发现并报告错误；调试（debugging）尝试定位原因并修复。越早发现 bug 修复越便宜。
Apex 提供：测试（沙箱/scratch org 中隔离执行测试的完整框架）和调试（System.debug 语句、调试日志、Replay/Interactive 调试器）。调试日志是事务中所有交互的记录（启用 trace flag 时生成）。Apex Replay Debugger 用调试日志模拟实时调试会话。
什么是 Apex Replay Debugger？
Apex Replay Debugger 是免费工具，用 VS Code 作为客户端检查调试日志来调试 Apex 代码。你期望调试器有的功能都有：逐步查看变量值、设置断点（在特定行暂停执行）、悬停查看变量当前值、逐步执行代码路径。
不再需要：手动解析成千上万行日志、到处撒 System.debug 语句、猜测不同执行点的变量值。协作更容易：可从任意 replay-enabled 调试日志启动；客户和同事可共享调试日志；异步调试——无需实时 org 连接。
什么是 Apex Interactive Debugger？
Apex Interactive Debugger（也在 Salesforce Extension Pack 里）用 VS Code 在沙箱/scratch org 上实时调试 Apex 代码。与 Replay Debugger 的关键区别：需要实时连接到 org、代码执行时实时调试、仅沙箱和 scratch org 可用。另有 ISV Customer Debugger（供 ISV 合作伙伴在订阅者 org 中调试，遵守托管代码保护）。Interactive Debugger 和 ISV Customer Debugger 是付费产品。本项目聚焦免费的 Apex Replay Debugger。
创建 Trailhead Playground
本项目创建一个全新的 Trailhead Playground：页面底部点击 Launch 旁的下拉箭头 → Create a Trailhead Playground。干净的 org 保证从一致的基线开始——无现有代码、无冲突配置。整个项目用它部署代码、跑测试、捕获调试日志、练习 Replay Debugger。
资源（单元一）
继续学习：Apex Replay Debugger for VS Code（Marketplace）、Apex Interactive Debugger for VS Code（Marketplace）、YouTube「Banish the Bugs with Apex Replay Debugger」、Debug Log Levels and Log Categories。下一步：设置 VS Code（Salesforce CLI、Salesforce Extensions、Java JDK）。
二、设置 Visual Studio Code
第二单元安装并配置完整的 Apex 开发环境：Visual Studio Code、Salesforce CLI、Salesforce Extension Pack、Java JDK。
安装与更新 Salesforce CLI
Salesforce CLI 控制完整应用生命周期：创建开发/测试环境、同步 org 和源码控制之间的代码、命令行执行测试。从 developer.salesforce.com 安装，用 sf update 验证。它是所有 Salesforce DX 工作流的基础——项目创建、org 授权、源码部署、测试执行都经由 CLI。
安装与更新 Visual Studio Code
Visual Studio Code 是强大、可定制、跨平台的编辑器，是 Force.com IDE 的桌面开发后继者。从 code.visualstudio.com 安装。VS Code + Salesforce Extensions = 你的新 Apex IDE；加上 Salesforce CLI，就有了 Lightning Platform 的完整开发环境。
安装 Salesforce Extensions
Salesforce Extension Pack 提供：Apex 代码补全和语法高亮、Apex 调试（Replay 和 Interactive）、SOQL 查询构建、org 管理、部署、Lightning Web Components 支持。安装：VS Code → View → Extensions → 搜索「salesforce extension pack」→ Install → 重新启动 VS Code。它把 VS Code 从通用编辑器变成专门的 Salesforce 开发环境。
安装 Java JDK
Java JDK 是 Salesforce Extensions 支持 Apex 的必需——为 VS Code 中代码智能提供支持的 Apex 语言服务器运行在 Java 上。推荐 JDK 21（或 17、11）。即使已装其他 Java 版本，也必须装这些推荐版本之一。记下安装目录（下一步配置 Java Home 要用）。
配置 Java Home 设置
Salesforce Extensions 通过 JAVA_HOME 或 JDK_HOME 环境变量查找 Java，也可在 VS Code 设置里显式设置。配置：File → Preferences → Settings → 搜索「apex java」→ 在 salesforcedx-vscode-apex.java.home 输入 JDK 安装目录 → 重新启动 VS Code → 新终端跑 java -version 验证。开发环境完整了。
资源（单元二）
继续学习：Trailhead「Quick Start — VS Code for Salesforce Development」、YouTube「Salesforce Development with VS Code」、Salesforce CLI、VS Code、Extension Pack（Marketplace）。下一步：创建 Salesforce DX 项目、写带 bug 的 Apex 代码、设置 Apex Replay Debugger。
三、设置 Apex Replay Debugger
第三单元创建 Salesforce DX 项目、写带故意 bug 的 Apex 类、创建能捕获它的测试类，并用 CLI 授权 Trailhead Playground。
创建 Salesforce DX 项目
在 VS Code 创建新的 SFDX 项目：Command Palette → SFDX: Create Project → Standard 模板 → 命名「debugger-project」→ 选文件夹 → Create。Explorer 显示标准 SFDX 结构，最重要的是 force-app/main/default/classes（Apex 代码所在，目前为空）。
创建 Apex 类
创建 AccountService.cls——带故意 bug 的类。用 SFDX: Create Apex Class 命令（不是 New File，因为 SFDX 命令同时创建必需的 metadata .xml）。方法 createAccount 创建 Account，但 bug 是：TickerSymbol = accountNumber（应该用 tickerSymbol）。别急着修！
创建 Apex 测试
创建 AccountServiceTest.cls 捕获 bug。测试断言 TickerSymbol 应等于传入的 'CRM'，但 bug 把它设成了 'SFDC'（账户编号）。测试会失败，揭示 bug 存在——但不会告诉你 bug 在代码哪里。那正是调试器要做的。
授权 Org
通过 CLI 把 VS Code 连到 Trailhead Playground：Command Palette → SFDX: Authorize an Org → 选登录 URL → alias「debuggerOrg」→ 浏览器登录 → Allow → 返回 VS Code 看到「Successfully authorized」。授权后所有 SFDX 命令（部署、跑测试、取调试日志）都指向这个 org。
资源（单元三）
继续学习：Salesforce Extension Pack（Marketplace）、Salesforce DX Developer Guide「Project Setup」、Debugging in Visual Studio Code（官方文档）。下一步：部署代码、跑测试、设置断点检查点、用 Replay Debugger 调试。
四、调试你的代码
第四单元是主事件：部署代码、跑失败的测试、设置断点和检查点、捕获 replay-enabled 调试日志、用 Replay Debugger 逐步执行代码找到 bug 的确切位置，然后修复、重新部署、验证测试通过。
部署元数据到 Org
把 Apex 代码推送到 Playground：右键 classes 文件夹 → SFDX: Deploy This Source To Org。这会部署两个文件（AccountService.cls 和 AccountServiceTest.cls）。如果部署选项不可用，先确认已授权 org。部署后代码就在 org 里了。
运行 Apex 测试
执行测试确认 bug 存在：Command Palette → SFDX: Run Apex Tests → 选 AccountServiceTest → 看 Output 面板 → FAILED！错误消息「incorrect ticker symbol」——期望 'CRM' 但得到 'SFDC'。错误消息告诉你什么错了；调试器告诉你哪里和为什么。
设置断点与检查点
断点（Breakpoint）：在特定行暂停执行，点击行号左侧设置（红色实心圆点），可设任意多个。检查点（Checkpoint）：带堆转储（heap dump）的特殊断点，捕获该点所有局部变量、静态变量和触发器上下文变量（红圈中间带线），最多 5 个、30 分钟后过期。
本项目：① 在 Account newAcct = new Account( 设断点 ② 光标定位到 return newAcct; ③ SFDX: Toggle Checkpoint ④ SFDX: Update Checkpoints in Org（关键——告诉 Salesforce 激活检查点以收集堆转储）。
运行 Apex 测试并获取调试日志
生成replay-enabled的调试日志（检查点激活）：① SFDX: Turn On Apex Debug Log for Replay Debugger（创建 trace flag，30 分钟有效）② SFDX: Run Apex Tests → AccountServiceTest（再次失败，符合预期）③ SFDX: Get Apex Debug Logs → 选最近测试运行的日志。日志在 VS Code 中自动打开——它是测试执行的完整记录，供 Replay Debugger 模拟实时会话。
回放 Apex 调试日志并找到 bug
回放调试日志：① 在 VS Code 打开下载的调试日志 ② 右键任意行 → SFDX: Launch Apex Replay Debugger with Current File ③ Debug 侧栏打开 ④ Debug 工具栏点 Continue → 前进到第一个断点 ⑤ 再点 Continue → 停在 return newAcct; 的检查点。
检查变量：tickerSymbol 参数 = 'CRM' ✓（传入值正确）；展开 newAcct → TickerSymbol = 'SFDC' ✗（错了！应是 'CRM'）。Bug 找到了：第 28 行 TickerSymbol = accountNumber 应为 TickerSymbol = tickerSymbol。
部署修复后的元数据
修复代码——只改一个字符：accountNumber → tickerSymbol，保存，然后右键 → SFDX: Deploy This Source to Org。一个错误的变量名导致了 bug，调试器几分钟就找到了。没有调试器，你可能要花数小时加 System.debug 语句反复重新部署。
运行 Apex 测试验证修复
验证 bug 已修复：SFDX: Run Apex Tests → AccountServiceTest → Output 面板显示 PASSED ✓。四个断言全部通过：Account 找到 ✓、Name='Salesforce' ✓、AccountNumber='SFDC' ✓、TickerSymbol='CRM' ✓（修复前是 'SFDC'）。
你完成了完整调试工作流：部署 → 测试 → 调试日志 → 回放 → 检查 → 修复 → 验证。这就是你 Salesforce 开发生涯中会反复用到的标准 Apex 调试模式。
资源（单元四）
继续学习：Apex Replay Debugger for VS Code（Marketplace）、YouTube「Banish the Bugs with Apex Replay Debugger」、Apex Developer Guide「Debugging Apex」、Salesforce Help「Set Up Debug Logging」、Debugging in Visual Studio Code。恭喜掌握 Apex 调试工作流！
文章来源：Trailhead - Find and Fix Bugs with Apex Replay Debugger