JavaScript 调试

需要进行架构审查：本文档旨在支持针对 React Native 的“旧”或“遗留”架构的开发。它可能适用也可能不适用于新架构的开发，需要审查并可能需要更新。有关 React Native Windows 中 React Native 架构的信息，请参阅新旧架构。

本页面详细介绍了如何调试 RNW 应用程序中的 JavaScript 代码，包括在哪些场景中支持哪些工具。您有两种不同的选择：直接调试和Web 调试。

除非另有说明，否则下面详述的每个调试场景都假定您正在从 Metro 打包器加载 JS 捆绑包，而不是加载预构建的捆绑包文件。

直接调试

直接调试是 RN 的新 JS 调试解决方案，也是新 RNW 项目中默认启用的解决方案。

使用直接调试时，您的应用程序的 JS 代码不是在外部 JS 引擎上运行（如 Web 调试），而是在其嵌入式引擎上运行（如常）。然后，您可以将调试器直接附加到嵌入式引擎。

直接调试需要 Metro 打包器，因为 Metro 提供了调试体验的关键部分，例如 JS 源映射。

直接调试工具支持

JavaScript 引擎	Edge 开发人员工具	Visual Studio	Visual Studio Code	Visual Studio Code 附带 React Native Tools
Hermes (默认)	✅	✅	✅	✅
Chakra	🟥	✅	🟥	🟥

重要提示：某些版本的 Hermes 存在已知的直接调试问题，这些问题可能会得到修复，届时此警告可以移除。在此期间，我们建议使用 Web 调试。

重要提示：直接调试相对较新，根据您选择的引擎和调试器，可能仍存在一些问题。有关详细信息，请参阅Web 与直接调试。

步骤 1：启用直接调试

您可以通过两种方式启用直接调试：在应用程序的本机代码中编译时启用，或通过应用内开发者菜单在运行时启用。

选项 1：在您的原生代码中设置`UseDirectDebugger`

通过在应用程序启动期间设置应用程序的 InstanceSettings 的 UseDirectDebugger 属性可以启用直接调试。

C++

修改您的 C++ RNW 应用程序

您需要使用以下内容编辑 App.cpp 中 App 的构造函数：

InstanceSettings().UseWebDebugger(false);
InstanceSettings().UseDirectDebugger(true);

修改您的 C# RNW 应用程序

您需要使用以下内容编辑 App.xaml.cs 中 App 的构造函数：

InstanceSettings.UseWebDebugger = false;
InstanceSettings.UseDirectDebugger = true;

然后，只需像往常一样重新构建并启动您的 RNW 应用程序即可。

对于新的 RNW 应用程序，UseDirectDebugger 在调试版本中默认为 true，在发布版本中默认为 false。

选项 2：使用开发者菜单

直接调试也可以通过应用内的开发者菜单在运行时启用。

当您的 RNW 应用程序运行时，按下 Ctrl+Shift+D 调出开发者菜单
点击启用直接 JS 调试

然后，应用程序应在启用直接调试的情况下自动刷新。

步骤 2：连接调试器

下一步是连接您选择的调试器。

Edge DevTools

Visual Studio

VS Code

VS Code 附带 React Native Tools

使用 Edge 开发人员工具

您可以使用 Edge 开发人员工具，通过 Edge 调试使用 Hermes JS 引擎的 RNW 应用程序。

如果您使用 Chrome，则使用 Chrome 开发人员工具的过程类似。

启动您的 RNW 应用程序（启用直接调试并运行 Metro）
在 Edge 中，打开 URL edge://inspect
确保发现网络目标的复选框已选中
点击发现网络目标旁边的配置...按钮
在目标发现设置下添加localhost:8081的条目，然后单击完成
刷新 edge://inspect 页面

留意页面底部“远程目标”部分中是否出现“Hermes React Native”条目。请注意，“远程目标”部分本身可能会在检测到有效目标之前被隐藏。

点击Hermes React Native条目下的inspect链接

您现在应该能够调试您的 RNW 应用程序。要设置断点，您首先需要通过 Metro 的源映射查找应用程序的 JS 源文件。

点击Sources选项卡
按 Ctrl+P 调出打开弹出窗口
找到您的目标源文件（手动或通过输入其名称）并打开它

确保您打开的文件是从 Metro 的源映射中获取的，即文件条目在文件名下方标记有 localhost:8081

您现在应该能够在应用程序的 JS 源文件中设置断点。

重要提示：左侧边栏中的“文件系统”选项卡通常允许您将应用程序的源文件夹添加到“工作区”以便于浏览。但是，从工作区打开的文件将不允许您正确设置断点。您必须通过上述 Ctrl+P 方法打开应用程序的源文件，断点才能正常工作。

如果您尝试设置断点但不起作用，请仔细检查打开的文件是否通过源映射打开。选项卡的标题应显示为绝对文件名，其工具提示应显示以 https://:8081/ 为前缀的实际路径。

使用 Visual Studio (Chakra)

您可以使用 Visual Studio 的内置脚本调试器，直接调试使用（默认）Chakra JS 引擎的 RNW 应用程序。

确保已安装 Visual Studio
打开项目中的 Visual Studio 解决方案文件（例如 MyApp.sln）
选项 A：让 Visual Studio 启动应用程序并开始调试
1. 确保 Metro 已在运行（即 npx react-native start）
2. 通过设置 Visual Studio 顶部命令栏中的下拉菜单，确保您的本机应用程序的所需配置（例如Debug）和平台（例如x64）
3. 在“解决方案资源管理器”中，右键单击您的本机应用程序项目（例如 MyApp (Universal Windows)）并选择“属性”
  1. 对于 C++ RNW 应用程序，打开“配置属性”>“调试”页面，将“调试器类型”设置为“仅脚本”，然后单击“确定”
  2. 对于 C# RNW 应用程序，打开“调试”选项卡，将“调试器类型”>“应用程序进程”设置为“脚本”，然后关闭属性
4. 在菜单栏中单击调试并选择开始调试
选项 B：将 Visual Studio 附加到已运行的应用程序
1. 确保您的本机应用程序和 Metro 已在运行（即使用run-windows 命令）
2. 单击 Visual Studio 菜单栏中的调试，然后选择附加到进程...
3. 查找并选择应用程序的本机进程（不是 Metro）
4. 确保附加到：设置为自动：脚本代码或脚本代码
如果附加到：设置为其他内容，请仔细检查应用程序进程的类型列中是否存在脚本。如果不存在，请确保您已在应用程序中启用了直接调试，然后单击刷新按钮。如果类型下存在脚本，但未在附加到：中，请单击选择...按钮并尝试手动勾选调试这些代码类型：> 脚本。
1. 点击附加按钮

一切运行后，您应该能够调试您的 RNW 应用程序。要设置断点，只需直接在 Visual Studio 中您的应用程序的 JS 源文件中进行设置。

要在 Visual Studio 中查看应用程序的 JS 源，您可以

直接打开文件（通过“文件”菜单中的“打开”>“文件...”或按 Ctrl+O）或
在“解决方案资源管理器”侧边栏中查找文件，路径为 Solution 'MyApp' > Script Documents > file://... > script block > https://:8081/...

使用 Visual Studio (Hermes)

您可以使用 Visual Studio 中“Node.js 开发”工作负载中的调试器，直接调试使用 Hermes JS 引擎的 RNW 应用程序。

确保您已安装带有Node.js 开发工作负载的 Visual Studio
不带解决方案文件启动 Visual Studio（不含代码继续）

重要提示：您不应该打开解决方案文件。存在一个已知问题，即尝试在项目解决方案打开时调试 JS，该问题可能会得到修复，届时此警告可以移除。

选项 A：让 Visual Studio 启动应用程序并开始调试

重要提示：Visual Studio 不支持启动应用程序并使用 Hermes 启动直接调试。

选项 B：将 Visual Studio 附加到已运行的应用程序
1. 确保您的本机应用程序和 Metro 已在运行（即使用run-windows 命令）
2. 单击 Visual Studio 菜单栏中的调试，然后选择附加到进程...
3. 确保连接类型：设置为JavaScript 和 TypeScript (Chrome DevTools/V8 Inspector)
如果您没有看到JavaScript 和 TypeScript (Chrome DevTools/V8 Inspector)，请确保您已为您的 Visual Studio 版本安装了Node.js 开发工作负载。
1. 确保连接目标：设置为 https://:8081
2. 确保附加到：设置为JavaScript 和 TypeScript
3. 从进程列表中找到并选择 Hermes
如果列表中没有看到 Hermes，请打开浏览器并导航到 https://:8081/json。复制 webSocketDebuggerUrl 的值（例如，类似 ws://[::1]:8081/inspector/debug?device=0&page=1 的内容），并将其用作连接目标。
1. 点击附加按钮

一切运行后，您应该能够调试您的 RNW 应用程序。要设置断点，只需直接在 Visual Studio 中您的应用程序的 JS 源文件中进行设置。

要在 Visual Studio 中查看应用程序的 JS 源，您可以

直接打开文件（通过“文件”菜单中的“打开”>“文件...”或按 Ctrl+O）或
在“解决方案资源管理器”侧边栏中查找文件，路径为 解决方案 'MyApp' > 脚本文档

使用 Visual Studio Code

您可以使用 VS Code 的内置 Node.js 调试器，直接调试使用 Hermes JS 引擎的 RNW 应用程序。

确保您已安装 VS Code
在 VS Code 中打开项目的根文件夹
点击 VS Code 菜单栏中的运行，然后选择添加配置...
选项 A：让 VS Code 启动所有内容并开始调试

重要提示：VS Code 的内置 Node.js 调试器不支持启动所有内容并开始调试。

选项 B：将 VS Code 附加到已运行的 Metro
1. 根据您是否已有 launch.json 文件，下拉菜单将允许您选择Node.js：附加（如果可用）或仅选择Node.js
如果您没有看到 Node.js，请在编辑器中不打开代码文件的情况下重试。
1. launch.json 文件中应该会出现一个新的（可能不正确）条目。为了正确调试，配置需要如下所示（name 无关紧要）：
```
{
    "name": "Attach",
    "port": 8081,
    "request": "attach",
    "skipFiles": [
        "<node_internals>/**"
    ],
    "outFiles": [
        "${workspaceFolder}/**/*"
    ],
    "type": "node"
}
```
1. 确保您的本机应用程序和 Metro 已在运行（即使用run-windows 命令）
2. 通过点击侧边栏中的按钮或按下 Ctrl+Shift+D 打开运行和调试侧边栏
3. 确保在“运行和调试”侧边栏顶部选中了新配置
4. 点击 ▶️ 按钮或在 VS Code 中按下 F5
观察侧边栏中的调用堆栈面板，以查看附加：远程进程是否表示调试器连接成功。请注意，VS Code 可能需要一分钟才能扫描您的源代码，然后断点才能正常工作。

一旦一切运行，您应该能够调试您的 RNW 应用程序。要设置断点，只需直接在 VS Code 中您的应用程序的 JS 源文件中进行设置。

记住保存 launch.json，以便将来可以重用此调试配置。

将 Visual Studio Code 与 React Native Tools 配合使用

您可以使用 VS Code 和 React Native Tools 扩展，直接调试使用 Hermes JS 引擎的 RNW 应用程序。

确保您已安装 VS Code 和 React Native Tools 扩展
在 VS Code 中打开项目的根文件夹
点击 VS Code 菜单栏中的运行，然后选择添加配置...，再选择React Native

如果您没有看到 React Native，请在编辑器中不打开代码文件的情况下重试。

选项 A：让 VS Code 启动所有内容并开始调试
1. 根据您是否已有 launch.json 文件，下拉菜单将：
  1. 提供调试配置列表。勾选调试 Windows Hermes - 实验性并点击确定。或者
  2. 引导您完成一系列提示。选择调试应用程序、Windows、直接模式下的应用程序(Hermes)。
2. launch.json 文件中应该会出现一个新的（可能不正确）条目。为了正确调试，配置需要如下所示（name 无关紧要）：
```
{
    "name": "Debug Windows Hermes - Experimental",
    "cwd": "${workspaceFolder}",
    "type": "reactnativedirect",
    "request": "launch",
    "platform": "windows"
}
```
1. 确保 Metro 和您的原生应用程序均未在运行
2. 通过点击侧边栏中的按钮或按下 Ctrl+Shift+D 打开运行和调试侧边栏
3. 确保在“运行和调试”侧边栏顶部选中了新配置
4. 点击 ▶️ 按钮或在 VS Code 中按下 F5
观察 VS Code 的调试控制台输出，查看调试器连接是否成功。这可能非常慢，但 VS Code 应该会自动启动 Metro，建立调试器连接，然后启动您的原生应用程序以下载捆绑包。
选项 B：将 VS Code 附加到已运行的 Metro
1. 根据您是否已有 launch.json 文件，下拉菜单将：
  1. 提供调试配置列表。勾选附加到 Hermes 应用程序并点击确定。或者
  2. 引导您完成一系列提示。选择附加到应用程序、直接模式下的应用程序(Hermes)、Hermes 引擎、localhost、8081。
2. launch.json 文件中应该会出现一个新的（可能不正确）条目。为了正确调试，配置需要如下所示（name 无关紧要）：
```
{
    "name": "Attach to Hermes application - Experimental",
    "cwd": "${workspaceFolder}",
    "type": "reactnativedirect",
    "request": "attach"
}
```
1. 确保您的本机应用程序和 Metro 已在运行（即使用run-windows 命令）
2. 通过点击侧边栏中的按钮或按下 Ctrl+Shift+D 打开运行和调试侧边栏
3. 确保在“运行和调试”侧边栏顶部选中了新配置
4. 点击 ▶️ 按钮或在 VS Code 中按下 F5
观察侧边栏中的调用堆栈面板，以查看附加：远程进程是否表示调试器连接成功。

一旦一切运行，您应该能够调试您的 RNW 应用程序。要设置断点，只需直接在 VS Code 中您的应用程序的 JS 源文件中进行设置。

记住保存 launch.json，以便将来可以重用此调试配置。

Web 调试

Web 调试（也称为远程 JS 调试）是 RN 和 RNW 项目最初的 JS 调试解决方案。

它通过在外部进程（通常是 Edge 或 Chrome 等网络浏览器）的 JS 引擎中运行您的应用程序的 JS 代码来工作。然后，您可以使用该外部进程的开发工具（即浏览器的网络开发工具）来调试您的应用程序。

Web 调试需要 Metro Packager，因为 Metro 代理了您的本机 Windows 应用程序和远程 JS 引擎之间的连接。

重要提示：Web 调试已在 RN 0.73 中正式标记为已弃用，并将在未来的版本中移除。

Web 调试工具支持

JavaScript 引擎	Edge 开发人员工具	Visual Studio Code 附带 React Native Tools
Hermes (默认)	✅	✅
Chakra	✅	✅

重要提示：由于您的代码在远程 JS 引擎中运行，因此应用程序的嵌入式引擎不会被使用。这可能会导致您的已发布应用程序在使用嵌入式引擎时行为不同。有关详细信息，请参阅Web 与直接调试。

步骤 1：启用 Web 调试

通过在应用程序启动期间设置应用程序的 InstanceSettings 的 UseWebDebugger 属性可以启用 Web 调试。

C++

修改您的 C# RNW 应用程序

您需要使用以下内容编辑 App.xaml.cs 中 App 的构造函数：

InstanceSettings.UseWebDebugger = true;
InstanceSettings.UseDirectDebugger = false;

修改您的 C++ RNW 应用程序

您需要使用以下内容编辑 App.cpp 中 App 的构造函数：

InstanceSettings().UseWebDebugger(true);
InstanceSettings().UseDirectDebugger(false);

然后，只需像往常一样重新构建并启动您的 RNW 应用程序即可。

除非另有说明，对于新的 RNW 应用程序，UseWebDebugger 默认为 false。

步骤 2：连接调试器

下一步是使用您选择的调试器/开发工具连接到 Metro。

这必须在原生应用程序尝试从 Metro 下载 JS 捆绑包之前发生。如果尚未附加调试器，Metro 将自动尝试设置 Edge 开发人员工具。

Edge DevTools

VS Code 附带 React Native Tools

使用 Edge 开发人员工具

您可以使用 Edge 开发人员工具在 Edge 中进行 Web 调试。

如果您使用 Chrome，则使用 Chrome 开发人员工具的过程类似。

启动您的 RNW 应用程序（启用 Web 调试并运行 Metro）
在 Edge 中，打开 URL https://:8081/debugger-ui/

Metro 可能已经打开了它，寻找一个React Native Debugger选项卡。

在页面上按下 Ctrl+Shift+J 以启动开发人员工具

您现在应该能够调试您的 RNW 应用程序。要设置断点，您可以在Sources选项卡下的debuggerWorker.js > localhost:8081 > src/ui中找到您的应用程序的 JS 源文件。

将 Visual Studio Code 与 React Native Tools 配合使用

您可以使用 VS Code 和 React Native Tools 扩展在其中进行 Web 调试。

重要提示：如果 Edge 开发人员工具（或其他调试器）已连接，您将无法将 VS Code 连接到 Metro。因此，在执行这些步骤之前，请仔细检查您是否没有打开任何以前的 React Native Debugger 浏览器选项卡。

确保您已安装 VS Code 和 React Native Tools 扩展
在 VS Code 中打开项目的根文件夹
点击 VS Code 菜单栏中的运行，然后选择添加配置...，再选择React Native

如果您没有看到 React Native，请在编辑器中不打开代码文件的情况下重试。

选项 A：让 VS Code 启动所有内容并开始调试
1. 根据您是否已有 launch.json 文件，下拉菜单将：
  1. 提供调试配置列表。勾选调试 Windows并点击确定。或者
  2. 引导您完成一系列提示。选择调试应用程序、Windows、经典应用程序。
2. launch.json 文件中应该会出现一个新的（可能不正确）条目。为了正确调试，配置需要如下所示（name 无关紧要）：
```
{
    "name": "Debug Windows",
    "cwd": "${workspaceFolder}",
    "type": "reactnative",
    "request": "launch",
    "platform": "windows"
}
```
1. 确保 Metro、您的原生应用程序和/或任何浏览器开发人员工具未在运行
2. 确保在“运行和调试”侧边栏顶部选中了新配置
3. 点击 ▶️ 按钮或在 VS Code 中按下 F5
观察 VS Code 的调试控制台输出，查看调试器连接是否成功。这可能非常慢，但 VS Code 应该会自动启动 Metro，建立调试器连接，然后启动您的原生应用程序以下载捆绑包。
选项 B：将 VS Code 附加到已运行的 Metro
1. 根据您是否已有 launch.json 文件，下拉菜单将：
  1. 提供调试配置列表。勾选附加到打包器并点击确定。或者
  2. 引导您完成一系列提示。选择附加到应用程序、经典应用程序、localhost、8081。
2. launch.json 文件中应该会出现一个新的（可能不正确）条目。为了正确调试，配置需要如下所示（name 无关紧要）：
```
{
    "name": "Attach to packager",
    "cwd": "${workspaceFolder}",
    "type": "reactnative",
    "request": "attach"
}
```
1. 确保只有 Metro 正在运行（即 npx react-native start）
2. 确保在“运行和调试”侧边栏顶部选中了新配置
3. 点击 ▶️ 按钮或在 VS Code 中按下 F5
观察 VS Code 的调试控制台输出，查看调试器连接是否成功。
1. 手动启动您的原生应用程序

一旦一切运行，您应该能够调试您的 RNW 应用程序。要设置断点，只需直接在 VS Code 中您的应用程序的 JS 源文件中进行设置。

记住保存 launch.json，以便将来可以重用此调试配置。

重要提示：如果您在使用 Web Debugging 连接 VS Code 时遇到困难，请在开始上述步骤之前仔细检查您是否没有运行 RNW 的任何部分（注意流氓 node.exe 进程）。

Web 与直接调试

如上所述，RNW 同时支持 Web 调试和直接调试，了解何时使用它们各自的优势非常重要。

Web 调试是两种调试解决方案中较旧、更成熟的一种。它依赖于 Web 开发人员已经熟悉的强大浏览器内调试工具。这加强了 RN 旨在使 Web 开发人员能够使用 Web 技术构建原生应用程序的宗旨。

然而，Web 调试并非没有局限性。主要问题是 JS 在不同的 JS 引擎中运行时行为可能略有不同。因此，通过使用浏览器运行 JS 来开发（和测试）您的应用程序，您可能会错过仅在应用程序正常运行嵌入式 JS 引擎时才会出现的错误或其他问题。

这要求开发人员在发布版本中仔细检查其应用程序的所有功能，否则可能会出现客户在生产环境中发现使用 Web 调试无法重现的错误的情况。

此外，RN 的某些部分，例如对原生模块方法的同步调用，只有在嵌入式 JS 引擎上运行时才有效。此类原生方法在使用 Web 调试时将不起作用。

使用直接调试，您可以在最终应用程序附带的相同引擎中调试 JS 代码。这消除了开发过程中因使用不同引擎而导致的此类错误。

然而，直接调试也有其自身的局限性。它更新，因此更可能出现设置和稳定性问题。此外，您想要使用的 JS 调试器可能不支持您希望应用程序使用的 JS 引擎。

值得注意的是，尽管 Web 调试目前可能足以满足您的需求，但 RN 和 RNW 团队都将未来的投入重点放在直接调试体验上。

其他工具

以下是一些您在调试 RNW 应用程序时可能觉得有用的其他工具。

React 开发人员工具

React 开发人员工具可用于检查应用程序的 React 组件层次结构并执行性能分析。它与 Web 或直接调试结合使用。

启动您的 RNW 应用程序（Metro 正在运行）
从命令行运行 npx react-devtools
当您的 RNW 应用程序运行时，按下 Ctrl+Shift+D 调出开发者菜单

React 开发人员工具应检测到开发者菜单打开并自动附加到您的应用程序。

适用于 Windows 的 React Native

0.79

原生模块 (Windows)

原生开发 (Windows)

直接调试

直接调试工具支持

步骤 1：启用直接调试

选项 1：在您的原生代码中设置`UseDirectDebugger`

修改您的 C++ RNW 应用程序

修改您的 C# RNW 应用程序

选项 2：使用开发者菜单

步骤 2：连接调试器

使用 Edge 开发人员工具

使用 Visual Studio (Chakra)

使用 Visual Studio (Hermes)

使用 Visual Studio Code

将 Visual Studio Code 与 React Native Tools 配合使用

Web 调试

Web 调试工具支持

步骤 1：启用 Web 调试

修改您的 C# RNW 应用程序

修改您的 C++ RNW 应用程序

步骤 2：连接调试器

使用 Edge 开发人员工具

将 Visual Studio Code 与 React Native Tools 配合使用

Web 与直接调试

其他工具

React 开发人员工具

直接调试

直接调试工具支持

步骤 1：启用直接调试

选项 1：在您的原生代码中设置UseDirectDebugger

修改您的 C++ RNW 应用程序

修改您的 C# RNW 应用程序

选项 2：使用开发者菜单

步骤 2：连接调试器

使用 Edge 开发人员工具

使用 Visual Studio (Chakra)

使用 Visual Studio (Hermes)

使用 Visual Studio Code

将 Visual Studio Code 与 React Native Tools 配合使用

Web 调试

Web 调试工具支持

步骤 1：启用 Web 调试

修改您的 C# RNW 应用程序

修改您的 C++ RNW 应用程序

步骤 2：连接调试器

使用 Edge 开发人员工具

将 Visual Studio Code 与 React Native Tools 配合使用

Web 与直接调试

其他工具

React 开发人员工具

选项 1：在您的原生代码中设置`UseDirectDebugger`