Windows 调试器的符号路径

项目
07/08/2024

符号路径指定 Windows 调试器（如 WinDbg、KD、CDB 和 NTST）查找符号文件的位置。有关符号和符号文件的详细信息，请参阅符号。

某些编译器（包括 Microsoft Visual Studio）将符号文件放在与二进制文件相同的目录中。符号文件和选中的二进制文件包含路径和文件名信息，使调试器能够自动查找符号文件。如果在生成可执行文件的计算机上调试用户模式进程，并且符号文件位于其原始位置，则调试器可以在不设置符号路径的情况下找到符号文件。

在大多数其他情况下，需要将符号路径设置为指向符号文件位置。

提示

使用 .symfix 设置公共Microsoft公共符号服务器的默认路径，这些服务器在很多情况下效果良好。

符号路径语法

调试器的符号路径是一个字符串，其中包含由分号分隔的多个目录路径。例如 C:\Dir1;C:\Dir2\DirA;C:\Dir2\DirB。

支持相对路径。但是，应在每个路径之前添加驱动器号或网络共享，除非始终从同一目录中启动调试器。还支持网络共享。

对于符号路径中的每个目录，调试器将在三个目录中查找。例如，如果符号路径包含 C:\Dir1 并且调试器正在查找 DLL 的符号信息，则调试器将按顺序查找以下目录中的符号信息：

C:\Dir1\symbols\dll
C:\Dir1\dll
C:\Dir1

然后，调试器对符号路径中的每个目录重复此过程。最后，调试器在当前目录中查找，然后在当前目录中附加 ..\dll。调试器根据调试的二进制文件追加..\dll或..\exe..\sys追加。

符号文件具有日期和时间戳。调试器始终查找与它正在调试的二进制文件上的时间戳匹配的符号。无需担心调试器使用它在此序列中首先找到的错误符号。有关符号文件不可用时响应的详细信息，请参阅匹配符号名称。

设置符号路径的一种方法是输入 .sympath 命令。有关设置符号路径的其他方法，请参阅本主题后面的“控制符号路径 ”。

在本地缓存符号

应在本地缓存符号。在本地缓存符号的一种方法是在符号路径中包含 cache*; 或 cache*localsymbolcache;*。

如果在符号路径中包含字符串 cache*;，则从该字符串右侧的任何元素加载的符号都存储在本地计算机的默认符号缓存目录中。例如，以下命令告知调试器从命名 \\someshare 的网络共享获取符号，并在本地计算机上的默认位置缓存符号。

.sympath cache*;\\someshare

如果在符号路径中包含字符串 cache*localsymbolcache;，则从该字符串右侧出现的任何元素加载的符号都存储在 localsymbolcache 目录中。

例如，以下命令通知调试器从网络共享 \\someshare 中获取符号，并将这些符号缓存在 c:\MySymbols 目录中。

.sympath cache*C:\MySymbols;\\someshare

使用符号服务器：srv*

如果连接到 Internet 或公司网络，访问符号的最有效方法是使用符号服务器（如公共 Microsoft公共符号服务器）。可以使用符号路径中的以下字符串之一来使用符号服务器。

字符串srv*

如果在符号路径中包含字符串 srv*，调试器将使用符号服务器从默认符号存储中获取符号。例如，以下命令告知调试器从默认符号存储中获取符号。这些符号不会在本地计算机上缓存。
```
.sympath srv*
```
字符串srv*symbolstore

如果在符号路径中包含字符串 srv*symbolstore ，调试器将使用符号服务器从 符号存储中获取符号。例如，以下命令告知调试器从 Microsoft符号服务器存储中获取符号。这些符号不会在本地计算机上缓存。
```
.sympath srv*https://msdl.microsoft.com/download/symbols
```
字符串srv*localsymbolcache*symbolstore

如果将字符串 srv*localcache*symbolstore 包含在符号路径中，调试器将使用符号服务器从 符号存储 获取符号，并将其缓存在 localcache 目录中。例如，以下命令告知调试器从Microsoft符号服务器获取符号，https://msdl.microsoft.com/download/symbols 并在中 c:\MyServerSymbols缓存符号。
```
.sympath srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols
```

如果计算机上具有手动放置符号的目录，请不要使用该目录作为从符号服务器获取的符号的缓存。相反，请使用两个不同的目录。例如，可以手动将符号放在 c:\MyRegularSymbols 中，然后指定用 c:\MyServerSymbols 缓存从服务器获取的符号。下面的示例演示如何在符号路径中指定这两个目录。

.sympath C:\MyRegularSymbols;srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols

有关符号服务器和符号存储的详细信息，请参阅自定义符号存储和符号服务器。

合并缓存* 和 srv*

如果在符号路径中包含字符串 cache*;，则从该字符串右侧的任何元素加载的符号都存储在本地计算机的默认符号缓存目录中。例如，以下命令告知调试器从 Microsoft符号服务器存储中获取符号，并将其缓存在默认符号缓存目录中。

.sympath cache*;srv*https://msdl.microsoft.com/download/symbols

如果在符号路径中包含字符串 cache*localsymbolcache;，则从该字符串右侧出现的任何元素加载的符号都存储在 localsymbolcache 目录中。

例如，以下命令告知调试器从 Microsoft符号服务器存储和缓存目录中的 c:\MySymbols 符号。

.sympath cache*C:\MySymbols;srv*https://msdl.microsoft.com/download/symbols

使用 AgeStore 减小缓存大小

可以使用 AgeStore 工具删除早于指定日期的缓存文件，或删除足够的旧文件，以便生成的缓存大小小于指定数量。如果下游存储太大，则缓存文件的清理非常有用。

延迟符号加载

调试器的默认行为是使用延迟符号加载，也称为延迟符号加载。这种加载意味着在需要符号之前不会加载符号。

更改符号路径（例如，通过使用 .sympath 命令）时，所有带有导出符号的已加载模块都会延迟重新加载。

如果新路径不再包含用于加载 PDB 符号的原始路径，则具有完整 PDB 符号的模块符号将延迟重新加载。如果新路径仍包含 PDB 符号文件的原始路径，则不会延迟重新加载这些符号。

可以使用 -s 命令行选项关闭 CDB 和 KD 中的延迟符号加载。还可以通过使用 ld load symbols 命令或使用 .reload 模块命令和选项来 /f 强制加载符号。

Azure DevOps Services Artifacts

符号服务器可用于 Azure DevOps Services 中的 Azure Artifacts。若要了解如何在 WinDbg 中使用 Azure Artifacts，请参阅使用 WinDbg 中的符号进行调试。有关 Azure 生成的符号的一般信息，请参阅 “符号”概述。

控制符号路径

若要控制符号路径，可以选择以下方法之一：

使用 .symfix 设置符号存储路径命令设置公共Microsoft符号服务器的默认路径，这些服务器在很多情况下效果良好。若要设置本地缓存，只需键入 .symfix C:\MyCache。
使用 .sympath 命令显示、设置、更改或追加到路径。
在启动调试器之前，请使用 _NT_SYMBOL_PATH 和 _NT_ALT_SYMBOL_PATH 环境变量设置路径。符号路径是通过在 _NT_ALT_SYMBOL_PATH 后附加 _NT_SYMBOL_PATH 创建的。通常，路径通过 _NT_SYMBOL_PATH. 但是，你可能想要在特殊情况下使用这些 _NT_ALT_SYMBOL_PATH 设置，例如，如果你有共享符号文件的专用版本。如果尝试通过这些环境变量添加无效目录，调试器将忽略此目录。
启动调试器时，请使用 -y 命令行选项设置路径。
仅在 WinDbg 中，可以使用文件 |符号文件路径命令或按 CTRL+S 显示、设置、更改或追加到路径。