最大路径长度限制

项目
07/18/2024

在 Windows API 中（以下段落中讨论了一些例外情况），路径的最大长度为 MAX_PATH，此项被定义为 260 个字符。系统按以下顺序构建本地路径：驱动器号、冒号、反斜杠、用反斜杠分隔的名称组件和终止 null 字符。例如，驱动器 D 上的最大路径为“D:\某个 256 个字符的路径字符串<NUL>”，其中“<NUL>”表示当前系统代码页的不可见终止 null 字符。（<> 字符在此用于醒目用途，不能作为有效路径字符串的一部分。）

例如，如果要将具有长文件名的 Git 存储库克隆到本身具有长名称的文件夹中，则可能会遇到此限制。

注意

Windows API 中的文件 I/O 函数在将名称转换为 NT 样式名称的过程中会将“/”转换为“\”，但使用“\\?\”前缀时除外，如以下小节中所述。

Windows API 的许多函数还具有 Unicode 版本，以允许最大总路径长度为 32,767 个字符的扩展长度路径。此类型的路径由反斜杠分隔的组件组成，每个组件都取决于 GetVolumeInformation 函数的 lpMaximumComponentLength 参数中返回的值（此值通常为 255 个字符）。要指定扩展长度路径，请使用“\\?\”前缀。例如，“\\?\D:\非常长的路径”。

注意

32,767 个字符的最大路径是近似值，因为系统可能会在运行时将“\\?\”前缀扩展为更长的字符串，并且此扩展适用于总长度。

“\\?\”前缀还可以用于根据通用命名约定 (UNC) 构建的路径。要使用 UNC 指定此类路径，请使用“\\?\UNC\”前缀。例如，“\\?\UNC\server\share”，其中“server”是计算机的名称，“share”是共享文件夹的名称。这些前缀并不用作路径本身的一部分。它们指示将路径传递给系统时修改量应最少，这意味着您不能用正斜杠来表示路径分隔符，不能用句点来表示当前目录，也不能用双点来表示父目录。由于“\\?\”前缀不能与相对路径一起使用，因此相对路径总字符数始终不能超过 MAX_PATH 个字符。

不需要对路径和文件名字符串执行任何 Unicode 规范化以供 Windows 文件 I/O API 函数使用，因为文件系统会将路径和文件名视为 WCHAR 的不透明序列。在对相关 Windows 文件 I/O API 函数的任何调用的外部执行应用程序所需的任何规范化时，都应考虑到这一点。

使用 API 创建目录时，指定的路径不能太长以致于无法附加 8.3 文件名（即目录名不能超过 MAX_PATH 减 12）。

Shell 和文件系统有不同的要求。可以使用 Shell 用户界面无法正确解释的 Windows API 来创建路径。

在 Windows 10 版本 1607 及更高版本中启用长路径

从 Windows 10 版本 1607 开始，许多常见的 Win32 文件和目录函数中删除了 MAX_PATH 限制。但是，你的应用必须选择支持新行为。

要为每个应用程序启用新的长路径行为，必须满足两个条件。必须设置注册表值，应用程序清单必须包含 longPathAware 元素。

用于启用长路径的注册表设置

重要

了解启用此注册表设置将只影响为利用新功能而修改的应用程序。开发人员必须将其应用声明为可感知长路径，如以下应用程序清单设置中所述。这不是将影响所有应用程序的更改。

注册表值 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled (Type: REG_DWORD) 必须存在并设置为 1。在首次调用受影响的 Win32 文件或目录函数后，系统（每个进程）将缓存此注册表值（请参见下面的函数列表）。在进程的生存期内，将不会重新加载注册表值。为了使系统上的所有应用都能识别该值，可能需要重新启动，因为某些进程可能在设置密钥之前已经启动。

你还可以将此代码复制到一个可以为你设置此项的 .reg 文件中，或者通过提升的特权在终端窗口中使用 PowerShell 命令：

注册表 (.reg) 文件
PowerShell

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem]
"LongPathsEnabled"=dword:00000001

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

注意

还可以在 Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths 中通过组策略控制此注册表设置。

应用程序清单会更新以声明长路径功能

应用程序清单还必须包含 longPathAware 元素。

<application xmlns="urn:schemas-microsoft-com:asm.v3">
    <windowsSettings xmlns:ws2="http://schemas.microsoft.com/SMI/2016/WindowsSettings">
        <ws2:longPathAware>true</ws2:longPathAware>
    </windowsSettings>
</application>

没有 MAX_PATH 限制的函数

如果你选择支持长路径行为，那么以下目录管理函数不再具有 MAX_PATH 限制：CreateDirectoryW、CreateDirectoryExW GetCurrentDirectoryW RemoveDirectoryW SetCurrentDirectoryW。

如果你选择支持长路径行为，那么以下文件管理函数不再具有 MAX_PATH 限制：CopyFileW、CopyFile2、CopyFileExW、CreateFileW、CreateFile2、CreateHardLinkW、CreateSymbolicLinkW、DeleteFileW、 FindFirstFileW、FindFirstFileExW、FindNextFileW、GetFileAttributesW、GetFileAttributesExW、SetFileAttributesW、GetFullPathNameW、GetLongPathNameW、MoveFileW、MoveFileExW、MoveFileWithProgressW、ReplaceFileW、SearchPathW、FindFirstFileNameW、FindNextFileNameW、FindFirstStreamW、FindNextStreamW、GetCompressedFileSizeW、GetFinalPathNameByHandleW。

另请参阅

文件管理函数

目录管理函数

GetVolumeInformation

通过