Compartilhar via


Limitação Máxima do Comprimento do Caminho

Na API do Windows (com algumas exceções discutidas nos parágrafos a seguir), o comprimento máximo de um caminho é MAX_PATH, que é definido como 260 caracteres. Um caminho local é estruturado na seguinte ordem: letra da unidade, dois-pontos, barra invertida, componentes de nome separados por barras invertidas e um caractere nulo de terminação. Por exemplo, o caminho máximo na unidade D é "D:\alguma cadeia de caracteres de caminho de 256 caracteres<NUL>", em que "<NUL"> representa o caractere nulo de terminação invisível para a página de código do sistema atual. (Os caracteres <> são usados aqui para maior clareza visual e não podem fazer parte de uma cadeia de caracteres de caminho válida.)

Por exemplo, você poderá atingir essa limitação se estiver clonando um repositório git que tem nomes de arquivo longos em uma pasta que tem um nome longo.

Observação

As funções de E/S de arquivo na API do Windows convertem "/" em "\" como parte da conversão do nome em um nome de estilo NT, exceto ao usar o prefixo "\\?\", conforme detalhado nas seções a seguir.

A API do Windows tem muitas funções que também têm versões Unicode para permitir um caminho de comprimento estendido para um comprimento total máximo de caminho de 32.767 caracteres. Esse tipo de caminho é composto por componentes separados por barras invertidas, cada um até o valor retornado no parâmetro lpMaximumComponentLength da função GetVolumeInformation (esse valor geralmente é de 255 caracteres). Para especificar um caminho de comprimento estendido, use o prefixo "\\?\". Por exemplo, "\\?\D:\caminho muito longo".

Observação

O caminho máximo de 32.767 caracteres é aproximado, pois o prefixo "\\?\" pode ser expandido para uma cadeia de caracteres mais longa pelo sistema no tempo de execução, e essa expansão se aplica ao comprimento total.

O prefixo "\\?\" também pode ser usado com caminhos construídos de acordo com a convenção de nomenclatura universal (UNC). Para especificar esse caminho usando UNC, use o prefixo "\\?\UNC\". Por exemplo, "\\?\UNC\server\share", em que "server" é o nome do computador e "share" é o nome da pasta compartilhada. Esses prefixos não são usados como parte do caminho em si. Eles indicam que o caminho deve ser enviado para o sistema com modificações mínimas, o que significa que você não pode usar barras para representar separadores de caminho ou um ponto para representar o diretório atual, ou pontos duplos para representar o diretório pai. Como você não pode usar o prefixo "\\?\" com um caminho relativo, os caminhos relativos são sempre limitados a um total de MAX_PATH caracteres.

Não é preciso executar nenhuma normalização Unicode em cadeias de caracteres de caminho e nome de arquivo para uso pelas funções da API de E/S de arquivo do Windows porque o sistema de arquivos trata o caminho e os nomes de arquivo como uma sequência opaca de WCHARs. Qualquer normalização que seu aplicativo exija deve ser executada considerando esses fatores, externa a quaisquer chamadas para funções de API de E/S de arquivo do Windows relacionadas.

Ao usar uma API para criar um diretório, o caminho especificado não pode ser tão longo que você não possa acrescentar um nome de arquivo 8.3 (ou seja, o nome do diretório não pode exceder MAX_PATH menos 12).

O shell e o sistema de arquivos têm requisitos diferentes. É possível criar um caminho com a API do Windows que a interface do usuário do shell não consegue interpretar corretamente.

Habilitar caminhos longos no Windows 10, versão 1607 e posterior

A partir do Windows 10, versão 1607, as limitações MAX_PATH foram removidas de muitas funções comuns de arquivo e diretório do Win32. No entanto, seu aplicativo deve aceitar o novo comportamento.

Para habilitar o novo comportamento de caminho longo por aplicativo, duas condições devem ser atendidas. Um valor do registro deve ser definido, e o manifesto do aplicativo deve incluir o elemento longPathAware.

Configuração do registro para habilitar caminhos longos

Importante

Entenda que habilitar essa configuração do registro afetará apenas os aplicativos que foram modificados para aproveitar o novo recurso. Os desenvolvedores devem declarar que seus aplicativos reconhecem o caminho longo, conforme descrito nas configurações de manifesto do aplicativo abaixo. Essa não é uma alteração que afetará todos os aplicativos.

O valor do registro HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled (Type: REG_DWORD) deve existir e ser definido como 1. O valor do registro será armazenado em cache pelo sistema (por processo) após a primeira chamada para um arquivo Win32 afetado ou função de diretório (veja abaixo a lista de funções). O valor do registro não será recarregado durante o tempo de vida do processo. Para que todos os aplicativos no sistema reconheçam o valor, uma reinicialização pode ser necessária porque alguns processos podem ter sido iniciados antes que a chave fosse definida.

Você também pode copiar esse código para um arquivo .reg que pode definir isso para você ou usar o comando do PowerShell em uma janela de terminal com privilégios elevados:

Windows Registry Editor Version 5.00

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

Observação

Essa configuração do registro também pode ser controlada por meio da Política de Grupo em Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths.

Atualizações de manifesto do aplicativo para declarar a funcionalidade de caminho longo

O manifesto do aplicativo também deve incluir o elemento 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>

Funções sem restrições MAX_PATH

Estas são as funções de gerenciamento de diretório que não têm mais restrições de MAX_PATH se você optar pelo comportamento de caminho longo: CreateDirectoryW, CreateDirectoryExW, GetCurrentDirectoryW, RemoveDirectoryW, SetCurrentDirectoryW.

Estas são as funções de gerenciamento de arquivos que não têm mais restrições de MAX_PATH se você optar pelo comportamento de caminho longo: 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.

Confira também

Funções de gerenciamento de arquivo

Funções de gerenciamento de diretório

GetVolumeInformation