调试 PWA Kit 应用程序

漏洞和性能瓶颈是 Web 应用程序开发中不可避免的一部分。借助 PWA Kit，可以使用各种工具和技术深入了解这些问题，从而仔细检查应用程序。

将本指南中的任何占位符替换为实际值。占位符的格式如 $PLACEHOLDER。

在遵循本指南中更有针对性的建议之前，请先尝试以下一般疑难解答步骤：

  • 在启动本地开发服务器之前，请仔细检查是否正在运行受支持的 Node 版本（请参阅入门指南）。
  • 确认开发服务器仍在运行，并且该端口尚未被其他进程接管。
  • 代码更改后，在重新加载浏览器之前确认消息 HTTP development server listening 出现在终端中。
  • 在浏览器控制台和终端中查找错误。
  • 使用浏览器的开发人员工具查找网络错误响应。（在 Chrome 的 DevTools 中，转到网络选项卡。）
  • 为了帮助识别句法错误和拼写错误，请运行代码格式化程序和 linter。Retail React App 中为 Prettier（代码格式化程序）和 ESLint (linter) 提供了配置文件。
  • 检查计算机的防病毒和防火墙设置是否有任何阻止代码运行或阻止网络请求的内容。
  • 要识别和分析性能问题，请使用 Chrome 的 DevTools 中的 Profiler。有关更多信息，请参阅 Google 提供的指南：分析运行时性能。还可以为 Chrome 安装 React Developer Tools 扩展，以获取另一个 Profiler 选项卡，可以在其中看到类似的信息，但在组件级别。

可以将两个特殊的查询参数添加到商务应用程序提供的任何 URL 中，以帮助调试服务器端代码的问题。

__server_only查询参数停止hydration 进程，以便页面在浏览器中的显示与服务器端渲染后完全一样。查看页面的服务器端渲染版本不仅有助于解决服务器端渲染问题，还有助于解决 SEO 问题，因为搜索引擎会抓取此版本的页面。

__pretty_print查询参数为 __PRELOADED_STATE__ 对象添加格式以使其更具可读性。该对象在 hydration 开始之前提供了应用程序状态的快照，因此有助于调试以查看它是否包含所期望的值。要查看对象的内容，请加载应用程序，查看页面的源代码，然后搜索 __PRELOADED_STATE__。

__PRELOADED_STATE__ 对象包含在应用程序开始在服务器端运行时最初请求的页面 HTML 源代码中的 <script> 标签中。__PRELOADED_STATE__ 对象包含从 getProps 函数返回的序列化值（包括附加到 _app 组件和页面组件的 getProps 版本）。

默认情况下，应用服务器会在终端中显示控制台消息，但不允许观察代码执行情况。此限制可能难以调试在服务器端（或本地计算机）呈现页面的代码。

为了增强调试，可以使用备用命令启动本地开发服务器，此命令作为可附加调试器 Node 内的检查流程运行。（有关更多详细信息，请参阅 Node 文档。）

可以将许多流行浏览器和文本编辑器中包含的调试器附加到 Node 的检查器进程。以下是 Google Chrome 和 Visual Studio Code 的说明。

  1. 打开终端。
  2. 前往项目目录。
  3. 使用 npm run start:inspect 开始本地 dev 服务。
  4. 要确认调试器正在侦听，请在终端输出中查找“调试器正在侦听”消息。
  5. 打开 Chrome 并输入 URL chrome://inspect。
  6. 点击打开 Node 的 DevTools。
  7. DevTools 在新窗口中打开。
  8. 要确认调试器已附加，请在终端输出中查找“已附加调试器”消息。
  9. 设置断点，添加 debugger 语句等。
  10. 从本地开发服务器的 Chrome 加载页面。
  11. 使用专用窗口进行调试。

现在即可跟踪服务器端代码的执行！

要了解有关在 DevTools 中使用断点进行调试的更多信息，请参阅 Google 提供的指南：调试 JavaScript。

  1. 在 Visual Studio Code 中打开项目文件。
  2. 从菜单栏中，点击终端 > 新终端。
  3. 使用 npm run start:inspect 开始本地 dev 服务。
  4. 打开命令面板。Windows 的快捷方式：Ctrl + Shift + P。Mac 的快捷方式：Command + Shift + P。
  5. 键入以下命令：“Debug to Node Process.”
  6. 将出现 Node 进程列表。选择列表中的第一个。
  7. 要确认调试器已附加，请在终端输出中查找“已附加调试器”消息。
  8. 设置断点、添加调试器语句等。
  9. 在 Web 浏览器中从本地开发服务器加载页面。
  10. 使用 Visual Studio Code 中的集成调试器进行调试。

现在即可在 Visual Studio Code 中跟踪服务器端代码的执行！

为避免重复附加 Node 进程，请打开命令面板并输入“调试：切换自动附加。”将设置切换为始终并在 Visual Studio Code 终端中重新启动本地开发服务器。

有三种方法可以调试部署到 Managed Runtime (MRT) 的代码：

  • 使用源映射精确定位错误发生的位置。
  • 尾日志，用于调试低容量环境中的实时问题或错误。
  • 对于生产环境，请使用 Log Center，它提供了强大的搜索和保留功能。

使用源映射来识别任何服务器端或客户端错误。源映射提供了一个简单的错误堆栈跟踪，可以精确定位错误发生的位置。例如，堆栈跟踪标识发生错误的文件和行号，以便更轻松地进行疑难解答。

启用源映射会影响性能，因此我们建议仅在非生产环境中使用此功能。

要使用源映射，必须使用 PWA Kit 版本 3.4.x 或更高版本生成站点。如果有更早的版本，请升级项目以使用 PWA Kit 3.4.x。

启用源映射有两种选择：使用 Runtime Admin 或使用 Managed Runtime API。

使用 Runtime Admin

  1. 登录到 Runtime Admin。
  2. 点击您的项目。
  3. 点击环境。
  4. 单击环境设置。
  5. 在高级部分中，点击编辑。
  6. 启用源映射。
  7. 在“高级”部分的顶部，单击**“更新”**。
  8. 等待捆绑包完成重新部署。

使用 Managed Runtime API

调用 projects_target_partial_updateAPI 端点并设置为 enable_source_maps 至 true。这会在您的环境中配置 NODE_OPTIONSManaged Runtime 环境变量--enable-source-maps，并重新部署捆绑包。

  1. 生成项目时，请使用以下局部环境变量生成 ssr.js.map 文件：PWA_KIT_SSR_SOURCE_MAP=true。
  1. 将捆绑包部署到 Managed Runtime。

启用并上传源映射后，可以使用 Managed Runtime 上的尾日志查看它们。

使用源映射可能会导致性能问题。例如，访问 error.stack 随时都存在延迟问题。因此，当您在代码中包含 console.error(e) 时，这可能会减慢您的网站速度。

  • **新的非生产环境：**将 enable_source_maps 设置为 true。
  • **新生产环境：**将 enable_source_maps 设置为 false。此行为有助于避免启用源映射功能时可能出现的潜在性能影响。
  • **所有预先存在的环境：**将 enable_source_maps 设置为 false。

当您的应用程序部署到 Managed Runtime 时，不支持远程调试。但是，您可以实时跟踪任何 Managed Runtime 环境的日志，以帮助诊断任何服务器端错误。

您有两个可以通过命令行跟踪日志的选项。

如果您正在使用从 2.4.1 或更高版本生成的 PWA Kit 项目，您可以：

  • 查看 logs 命令的帮助：npm run tail-logs -- --help
  • 跟踪特定项目和环境的日志：npm run tail-logs -- --environment $ENV_ID

必须在上述命令中使用额外的 --。

如果您在 PWA Kit 项目之外工作，或者拥有根据 2.4.1 之前版本生成的项目，您可以使用 npx：

  • 查看 logs 命令的帮助：npx @salesforce/pwa-kit-dev tail-logs --help
  • 跟踪特定环境 ID 和项目 ID 的日志：npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

您还可以使用较短的 -e 和 -p 参数来代替 --environment 和 --project 参数。

跟踪日志时，请记住以下限制：

  • 每个日志跟踪会话将在 60 分钟后终止。
  • 每个环境一次最多可以支持所有用户的 100 个活动日志跟踪会话。
  • 要追踪日志，您需要获得 Managed Runtime 项目的开发人员或管理员用户权限。

如果您使用 PWA Kit 构建站点或拥有 B2C Commerce 实例，请使用 Log Center 疑难解答。Log Center：

  • 提供从 Managed Runtime (MRT) 和 B2C Commerce 实例访问日志的单一位置。将 MRT 环境中发生的情况与 B2C Commerce 实例中发生的情况联系起来。
  • 允许您搜索和过滤许多历史日志。您可以获取有关生产环境发生情况的详细信息，以帮助更快地调查和解决问题。
  • Log Center 中的 MRT 日志仅适用于生产环境。请参阅前提条件。
  • 从事件发生到日志出现在 Log Center 中，最高可能有 15 分钟的延迟。

本指南重点介绍如何使用 PWA Kit 构建的站点进行调试。有关将 Log Center 与您的 B2C Commerce 实例结合使用的信息，请参阅集中式 Log Center。

要访问 Log Center 环境中的 MRT 日志，您必须先：

  1. 在 Account Manager 中拥有 Log Center 用户角色。要验证，请在 Account Manager中检查您的角色。如果您没有该角色，请让您的 Account Manager 管理员授予您访问权限。请参阅为 Salesforce B2C Commerce 用户管理 Account Manager。

  2. 按如下方式设置环境：

    a.将环境标记为生产环境。请参阅与生产环境相关的详细信息和限制。

    b.选择要连接到环境的 Commerce Cloud (B2C Commerce) 实例。

    c.添加一个或多个站点 ID 以与环境相关联。

完成前提条件后，要在 Log Center 中查看 MRT 日志，请执行以下操作：

  1. 启动 Log Center。
  2. 选择区域。
  3. 选择**领域**。如果不知道自己的域 ID，请询问 Account Executive (AE) 或 Customer Success Manager (CSM)。
  4. 单击显示筛选结果。
  5. 单击搜索 > 当前搜索。
  6. 在“服务类型”下，选择**“mrt”**。
  7. 在“主机”下，选择要查看其 MRT 日志的生产环境。主机的格式为 $PROJECT.$ENVIRONMENT。如果您有多个 MRT 生产环境，则可以看到多个 MRT 主机名。
  8. 查看 MRT 日志。

有关 Log Center 中日志级别和日志量的信息，请参阅管理员配置。