Windows 调试器的符号路径

项目
12/29/2023

符号路径指定 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

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

合并 cache* 和 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 set 符号存储路径命令设置公共 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 可显示、设置、更改或追加到路径。