Windows 调试器的符号路径

符号路径指定 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 符号服务器 存储区获取符号,并将符号缓存在 中 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 symbol store path 命令 设置公共 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 可显示、设置、更改或追加到路径。

如果使用 -sins 命令行选项,调试器将忽略符号路径环境变量。

疑难解答

使用 !sym noisy-nWinDbg Command-Line 选项 在加载符号时显示其他详细信息。 有关其他故障排除策略,请参阅 验证符号

另请参阅

高级 SymSrv 使用