Case Summary: Azure Files 共享中 PDF 文件因路径超过 260 字符无法打开

Product/Service: Azure Files (SMB)

1. 症状 (Symptoms)

  • 客户报告在 Azure Files 共享文件夹中，某些 PDF 文件无法直接打开。
  • 使用 Adobe Acrobat 打开 PDF 时返回错误。
  • 使用 Edge 浏览器打开时，直接显示 “New Tab” 空白页面。
  • 将这些 PDF 文件下载到本地后，可以正常打开。
  • 上传和下载文件到共享文件夹均正常。
  • 在同一共享路径下创建和修改 Word 或 Excel 文件时未出现问题（后来发现是因为这些文件的文件名较短）。

2. 背景 (Background / Environment)

  • 共享存储：Azure Files（SMB 协议挂载）
  • 共享路径示例：\\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\...
  • 客户端操作系统：Windows
  • 涉及应用程序：Adobe Acrobat、Microsoft Edge
  • 问题特征：仅影响路径较长的文件，路径较短的文件不受影响

3. Troubleshooting 过程 (Investigation & Troubleshooting)

  1. 收集 Procmon 日志并分析
    • 对不同场景下打开 PDF 文件进行了统计和分析。
    • 发现：无法打开的文件路径总长度均大于 260 个字符。
  2. 路径长度对比验证
    • 在同一共享路径下，文件名较短（路径总长未超过 260 字符）的 PDF 可以正常打开。
    • 问题文件路径示例：
      \\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\Intra-company agreement (TSS is service provider)\2026\ITBJ-202601-0002-0002_ContosoK_Intracompany_Agreement_to_2025_TSS_Statement_Of_Work.pdf
      该路径已超出 260 个字符的限制。
    • 结论：问题与 Windows MAX_PATH（260 字符）限制直接相关。
  3. 本地复现测试
    • 在本地环境中成功复现了该问题。
    • 当路径长度大于 260 个字符且文件系统未启用 “Short file names (8.3 Alias)” 功能时，文件 Location 会显示 \\?\path 的形式。
    • 此时 PDF 文件无法用 Edge 和 Adobe 打开。
    • 同时出现其他异常行为：文件属性中看不到 Security tab、重命名文件无效等。
  4. 测试 Short File Names (8.3 Alias) 方案
    • 在路径名不变的情况下，如果系统启用了 “Short file names (8.3 Alias)” 功能，Location 会显示 xxx~1 短名形式。
    • 使用短名后路径长度小于 260 的限制，PDF 文件可以正常打开。
    • 但是：Azure Storage 文档明确指出，Azure Files 目前不支持 Short file names (8.3 Alias) 功能，客户无法使用此方案。
  5. 测试 LongPathsEnabled 注册表方案
    • 系统层面有注册表 HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled 可在 FileSystem 层面启用长路径支持。
    • 但是：该功能需要应用程序本身兼容长路径。目前 Edge 和 Adobe Acrobat 暂不支持该功能。
  6. 测试关闭 Adobe 实时保护
    • 关闭 Adobe 的实时保护功能后，似乎可以绕过字符限制并成功打开 PDF。
    • 具体处理逻辑涉及第三方技术实现，无法解释原理。

4. Blockers 与解决 (Blockers & How They Were Resolved)

Blocker 影响 如何解决
Azure Files 不支持 8.3 短文件名 无法通过启用短文件名来缩短路径长度 转向映射更深层目录的方案
Edge 和 Adobe 不支持 LongPathsEnabled 即使系统启用长路径，应用程序也无法利用该功能 确认为应用层限制，转向路径缩短方案

5. 根因与解决方案 (Root Cause & Resolution)

Root Cause

Windows 系统存在 MAX_PATH 260 字符的路径长度限制。当 Azure Files 共享路径中的文件完整路径超过 260 个字符时，文件的 Location 以 \\?\path 形式呈现。Edge 和 Adobe Acrobat 不兼容 \\?\ 前缀路径格式，也不支持 LongPathsEnabled 长路径功能，导致无法正常打开这些 PDF 文件。同时，Azure Files 不支持 Short file names (8.3 Alias) 功能，无法通过短名缩短路径。

Resolution

方案：映射更深层目录（减少路径长度）

将驱动器映射到共享路径中较深层级的目录，从而减少可见路径长度：

  1. 选择共享路径中尽可能深的目录作为映射点。例如将：
    \\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\Intra-company agreement (TSS is service provider)
    映射为本地盘符 Z:。
  2. 映射后访问文件路径变为：
    Z:\2026\ITBJ-202601-0002-0002_ContosoK_Intracompany_Agreement_to_2025_TSS_Statement_Of_Work.pdf
    大幅缩短了前缀路径占用的字符数，使总路径长度小于 260 字符。
  3. 验证映射后 PDF 文件可以正常用 Adobe 和 Edge 打开。

Workaround

  • 关闭 Adobe 实时保护功能：在 Adobe Acrobat 中关闭实时保护功能后，似乎可以绕过 260 字符路径限制直接打开 PDF。但此方法的原理涉及第三方实现细节，不推荐作为正式方案。

6. 经验教训 (Lessons Learned)

  • 技术知识：
    • Windows MAX_PATH 260 字符限制不仅影响文件操作，还会导致文件属性显示异常（如 Security tab 消失、重命名失效等）。
    • LongPathsEnabled 注册表仅对支持该功能的应用程序有效，Edge 和 Adobe 目前不支持。
    • Azure Files 明确不支持 8.3 短文件名功能，这在本地文件共享中可用的方案在 Azure 场景下不适用。
  • 排查方法：
    • 遇到”部分文件无法打开，部分可以”的场景时，应优先检查文件路径长度差异。
    • 使用 Procmon 对比能打开和不能打开的文件路径长度是一个有效的排查手段。
  • 预防措施：
    • 如果目标路径是本地路径或 Windows 文件共享，可以尝试启用 Short file names (8.3 Alias)，启用后需对文件或文件夹做小改动（如重命名）才能让短名路径生效。
    • 如果目标路径不支持 8.3 短文件名（如 Azure Files），则应考虑映射更深层目录来减少路径长度。
    • 在设计共享文件夹目录结构时，应尽量避免过深的嵌套和过长的文件夹名称。

7. 参考文档 (References)

  • [fsutil 8dot3name Microsoft Learn](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/fsutil-8dot3name) — 管理 8.3 短文件名的命令行工具说明
  • Azure Files SMB Protocol - Limitations — Azure Files SMB 协议的功能限制说明（包括不支持 8.3 短文件名）
  • Maximum Path Length Limitation - Win32 apps — Windows MAX_PATH 260 字符路径长度限制详解

Case Summary: PDF Files Fail to Open in Azure Files Share Due to Path Exceeding 260 Characters

Product/Service: Azure Files (SMB)

1. Symptoms

  • Customer reported that certain PDF files in an Azure Files share could not be opened directly.
  • Opening PDFs with Adobe Acrobat returned errors.
  • Opening with Microsoft Edge displayed a blank “New Tab” page.
  • Downloading these files locally allowed them to open normally.
  • Uploading and downloading files to/from the share worked without issues.
  • Creating and modifying Word or Excel files in the same share path had no issues (later found to be because those file names were shorter).

2. Background / Environment

  • Shared Storage: Azure Files (mounted via SMB protocol)
  • Share Path Example: \\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\...
  • Client OS: Windows
  • Affected Applications: Adobe Acrobat, Microsoft Edge
  • Problem Characteristic: Only files with long paths were affected; files with shorter paths in the same share worked fine.

3. Investigation & Troubleshooting

  1. Collected and analyzed Procmon logs
    • Captured Procmon traces for different scenarios of opening PDF files.
    • Finding: All files that failed to open had a total path length exceeding 260 characters.
  2. Path length comparison verification
    • In the same share path, PDF files with shorter names (total path under 260 characters) opened normally.
    • Example of a problematic file path:
      \\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\Intra-company agreement (TSS is service provider)\2026\ITBJ-202601-0002-0002_ContosoK_Intracompany_Agreement_to_2025_TSS_Statement_Of_Work.pdf
      This path exceeded the 260-character limit.
    • Conclusion: The issue was directly related to the Windows MAX_PATH (260 character) limitation.
  3. Local reproduction test
    • Successfully reproduced the issue in a local environment.
    • When path length exceeded 260 characters and “Short file names (8.3 Alias)” was not enabled, the file Location displayed in \\?\path format.
    • PDF files could not be opened with Edge or Adobe in this state.
    • Additional anomalies observed: Security tab missing from file properties, file renaming not working, etc.
  4. Tested Short File Names (8.3 Alias) solution
    • With “Short file names (8.3 Alias)” enabled, the Location displayed in xxx~1 short name format.
    • Using short names brought the path length under the 260-character limit, allowing PDFs to open normally.
    • However: Azure Storage documentation explicitly states that Azure Files does not support Short file names (8.3 Alias), making this solution unavailable for the customer.
  5. Tested LongPathsEnabled registry solution
    • The system-level registry key HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled can enable long path support at the file system level.
    • However: This feature requires application-level compatibility. Edge and Adobe Acrobat currently do not support this feature.
  6. Tested disabling Adobe real-time protection
    • Disabling Adobe’s real-time protection feature appeared to bypass the character limit and allowed PDFs to open successfully.
    • The underlying mechanism involves third-party implementation details and could not be explained.

4. Blockers & How They Were Resolved

Blocker Impact How Resolved
Azure Files does not support 8.3 short file names Cannot use short file names to shorten path length Pivoted to mapping deeper directories approach
Edge and Adobe do not support LongPathsEnabled Even with system-level long path enabled, applications cannot leverage the feature Confirmed as application-layer limitation, pivoted to path shortening approach

5. Root Cause & Resolution

Root Cause

Windows has a MAX_PATH limitation of 260 characters. When the full file path in an Azure Files share exceeds 260 characters, the file Location is presented in \\?\path format. Edge and Adobe Acrobat are not compatible with the \\?\ prefix path format and do not support the LongPathsEnabled long path feature, resulting in failure to open these PDF files. Additionally, Azure Files does not support Short file names (8.3 Alias), preventing path shortening through short names.

Resolution

Solution: Map a drive to a deeper directory level to reduce path length

Map the drive letter to a deeper subdirectory within the share path to reduce the visible path length:

  1. Choose a directory as deep as possible within the share path as the mapping point. For example, map:
    \\storageacct01.file.core.windows.net\corp-public\Contoso Company Center\Sharing Centre\Intra-company Agreements (TSS is service provider)\Intra-company agreement (TSS is service provider)
    to local drive Z:.
  2. After mapping, the file path becomes:
    Z:\2026\ITBJ-202601-0002-0002_ContosoK_Intracompany_Agreement_to_2025_TSS_Statement_Of_Work.pdf
    This significantly reduces the prefix path characters, bringing the total path length under 260 characters.
  3. Verify that mapped PDF files can be opened normally with Adobe and Edge.

Workaround

  • Disable Adobe real-time protection: Disabling the real-time protection feature in Adobe Acrobat appeared to bypass the 260-character path limitation and open PDFs directly. However, the underlying mechanism involves third-party implementation details and is not recommended as an official solution.

6. Lessons Learned

  • Technical Knowledge:
    • The Windows MAX_PATH 260-character limitation affects not only file operations but also causes anomalies in file properties (e.g., missing Security tab, ineffective renaming).
    • The LongPathsEnabled registry key only works for applications that explicitly support the feature — Edge and Adobe currently do not.
    • Azure Files explicitly does not support 8.3 short file names, meaning solutions available for local/on-premises file shares may not apply in Azure scenarios.
  • Troubleshooting Method:
    • When encountering “some files fail to open while others work” scenarios, checking file path length differences should be a first priority.
    • Using Procmon to compare path lengths between files that can and cannot open is an effective diagnostic approach.
  • Preventive Measures:
    • For local paths or Windows file shares, try enabling Short file names (8.3 Alias). After enabling, files/folders need minor modifications (e.g., rename) for short name paths to take effect.
    • For paths that do not support 8.3 short file names (e.g., Azure Files), consider mapping a drive to a deeper directory to reduce path length.
    • When designing shared folder directory structures, avoid deep nesting and excessively long folder names.

7. References

  • [fsutil 8dot3name Microsoft Learn](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/fsutil-8dot3name) — Command-line tool documentation for managing 8.3 short file names
  • Azure Files SMB Protocol - Limitations — Azure Files SMB protocol feature limitations (including no 8.3 short file name support)
  • Maximum Path Length Limitation - Win32 apps — Detailed explanation of Windows MAX_PATH 260-character path length limitation