git解决Filename too long错误【排查】

Windows 上 git clone 报“Filename too long”错误，是因系统 MAX_PATH 默认限制 260 字符（含盘符、分隔符及文件名），Git 检出时调用 Windows API 创建深层路径失败；常见于 node_modules 嵌套、iOS Pods 或 Ja va 生成路径等场景。

说起来你可能不信，这个“文件名过长”的错误，锅还真不能全甩给 Git。背后真正捣鬼的，是 Windows 系统自己设下的那道 260 字符的“长城”——MAX_PATH 默认限制（含盘符、所有反斜杠和文件名）。Git 下载文件本身没问题，但到了检出那一步，它调用 Windows API 去创建深层路径里的文件时，系统直接甩回一句“不行”，于是就有了 fatal: cannot create directory at 'xxx': Filename too long 或 error: unable to create file xxx: Filename too long。

哪些场景最容易踩坑？来，对号入座：

• 项目放在 C:\Users\YourName\Documents\GitHub\... 这种长路径底下
• 前端项目带着 node_modules，尤其里面嵌套了 scope 包（比如 @types/react-router-dom）
• iOS 项目里的 Pods/ 或 Swift Package 依赖，路径动辄十几层
• Ja va/Ma ven 项目生成的 shaded jar，路径里夹杂着超长的 classifier 和时间戳

检查当前 core.longpaths 是否已启用

别急着动手改系统，先看看是不是 Git 配置压根没开——很多小伙伴装完 Git for Windows 后，根本没碰过这个开关。

打开 Git Bash 或命令行，敲一句：

git config --get core.longpaths

如果返回 false 或者啥都没有，那说明还没启用；如果返回 true 却依然报错，那就得排查系统级限制是否真的解除了，或者路径已经飙到了 32767 字符的极限（虽然极少见）。

注意作用域的优先级：--local > --global > --system。万一某个仓库目录下的 .git/config 里显式写了 longpaths = false，那它会把全局设置给覆盖掉。

快速启用长路径支持（推荐首选）

对绝大多数情况来说，一条命令就能搞定，连重启都不用：

• 全局启用（影响所有仓库）：

  git config --global core.longpaths true

• 仅对当前仓库启用（适合没管理员权限的环境）：

  git config core.longpaths true

• 克隆时临时启用（适合单次操作）：

  git clone -c core.longpaths=true  

执行完再跑一次 git config --get core.longpaths，确认返回 true。如果仍然报错，八成是 Git 进程没读到新配置——关掉终端重开，或者重启一下 IDE（像 VS Code、IntelliJ 之类的），问题基本消失。

Windows 系统级长路径支持必须打开

这一步最容易被忽视：哪怕 core.longpaths = true 设好了，如果 Windows 系统自己还锁着长路径开关，Git 底层调用 API 时照样会失败。两把钥匙缺一把都不行。

根据你的系统版本，选一个操作：

• Windows 10/11 专业版/企业版：运行 gpedit.msc → 计算机配置 → 管理模板 → 系统 → 文件系统 → 找到“启用 Win32 长路径” → 设为“已启用” → 重启电脑
• Windows 家庭版：运行 regedit → 定位到 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem → 把 LongPathsEnabled 的 DWORD 值改成 1 → 重启电脑

注册表项如果不存在，手动新建一个就行。修改前最好先把原值导出备份一下。这个设置是系统级的开关，Git 的 core.longpaths 只有站在它的肩膀上才能真正生效。

比较棘手的是：有些企业环境禁用了组策略或注册表编辑器。那只能换个思路——把仓库克隆到根目录下，比如 D:\p\，强行压短初始路径长度。这招虽然土，但实测屡试不爽。