Windows 环境下拉取大模型遇到 Filename too long 报错的彻底根治方案

💥 一、Windows 经典痛点：MAX_PATH 260 限制

在 Windows 10/11 或 Windows Server 环境下通过命令行或 Python 下载大模型时，很多开发者会遭遇诸如 Filename too long、OSError: [Errno 22] Invalid argument 或 Git checkout-index: unable to create file 等报错。

这是由于自 1980 年代 MS-DOS 时代遗留下来的系统级常数 MAX_PATH = 260 字符限制所导致的。

而 Hugging Face 默认的缓存结构包含组织名、仓库名、完整 40 位 SHA-1 commit 哈希以及分卷文件名，路径长度极易突破 260 字符限制：

C:\Users\Administrator\.cache\huggingface\hub\models--meta-llama--Llama-3.3-70B-Instruct\snapshots\a7569e0618ff9f4b3bf59c3a37d6e6a17b8f9e01\model-00028-of-00030.safetensors (共 274 个字符，超过 260 限制！)

🛠️ 二、四步彻底解决 Windows 路径过长难题

步骤 1：解锁系统注册表 LongPathsEnabled

在 Windows 10（1607 版本以上）与 Windows 11 中，微软已经原生内置了长路径支持，但默认处于关闭状态。以管理员身份运行 PowerShell 并执行：

PowerShell 解锁注册表

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

Write-Host "系统级长路径支持已激活！" -ForegroundColor Green

步骤 2：配置 Git 全局 longpaths 支持

Git for Windows 客户端有其独立的路径截断策略，需单独执行：

Git 开启长路径支持

git config --system core.longpaths true

步骤 3：重定向 HF_HOME 至盘符根目录（最立竿见影的技巧）

不要将模型缓存在深层的 C:\Users\用户名\... 目录下。在 Windows 环境变量中将 HF_HOME 设置为简洁的根路径（例如 D:\hf_cache），不仅路径长度直接立减 60 字符，还能避免 C 盘系统盘爆满：

PowerShell 一键配置系统级环境变量

# 在 PowerShell 中临时生效或写入系统环境变量
[System.Environment]::SetEnvironmentVariable('HF_HOME', 'D:\hf_cache', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.net', [System.EnvironmentVariableTarget]::User)

Write-Host "已将模型主目录定向到 D:\hf_cache，并配置镜像源加速！" -ForegroundColor Cyan

步骤 4：Python 代码中的 \?\ 扩展前缀

如果你在编写读写权重的底层 Python 脚本，可以使用 Windows 扩展路径前缀 \\?\，它能显式绕过所有 Win32 路径规范化层，最大支持 32,767 字符长度：

兼容 Windows 超长路径的 Python 封装

import os

def safe_open_path(path_str):
    # 将标准绝对路径转换为 Windows 扩展长路径
    abs_path = os.path.abspath(path_str)
    if os.name == 'nt' and not abs_path.startswith('\\\\?\\'):
        return '\\\\?\\' + abs_path
    return abs_path