解决 Windows 下 Git 的 “filename too long” 错误
你有没有过这样的经历：兴致勃勃地克隆一个开源项目，Git Bash 突然弹出一行红色报错——filename too long；或者在提交代码时，深层目录下的文件始终无法添加到暂存区，反复提示路径过长？
如果你在 Windows 上使用 Git，大概率踩过这个“坑”。其实，这不是 Git 的问题，而是 Windows 系统的“老规矩”在作祟。今天这篇文章，从问题根源到解决方案，再到避坑要点，帮你一次性搞定，从此告别“长路径”困扰。
一、为什么 Windows 上的 Git 会报“文件名过长”？
这个问题的根源在于 Windows 系统的路径长度限制 与 Git 仓库中常见的深层目录结构发生冲突。
- Windows 有一个默认规则：文件的完整路径（从盘符开始到文件名结束）不能超过 260 个字符。
- 而很多项目（尤其是 Java、C# 等后端项目）习惯采用多层目录组织代码，加上 Git 仓库本身的路径，很容易超过这个限制。
- 此时 Git 就会“卡壳”，因为 Windows 不允许它创建路径过长的文件。
注意：这是 Windows 系统的限制，在 macOS 或 Linux 上基本不会遇到。
二、3 种解决方案，从简单到彻底
根据你的 Windows 版本和操作权限，这里整理了 3 种实用的解决方案，按“操作难度递增、解决效果更彻底”排列，可按需选择。
✅ 方案 1：Git 自身配置（最快，推荐首选）
这是最简单的方案，只需给 Git 开启“长路径支持”，无需修改系统设置。
- 以管理员身份打开 Git Bash 或命令提示符。
- 执行以下命令（全局生效）：
git config --global core.longpaths true
3. 验证是否成功：
git config --get core.longpaths
若返回 true，说明配置成功。
4. 重启终端或 IDE，再次操作即可。
⚠️ 注意：此方法对绝大多数情况有效，但如果路径长度超过 Windows 的“终极上限”32767 个字符（极少见），仍需搭配系统级方案。
✅ 方案 2：系统级开启长路径（适合 Windows 专业版/企业版）
如果你的系统是 Windows 10/11 专业版或企业版，可通过组策略编辑器彻底解除路径长度限制。
5. 按 Win + R，输入 gpedit.msc，回车。
6. 依次展开：计算机配置 → 管理模板 → 系统 → 文件系统
7. 双击右侧的 “启用 Win32 长路径”，选择“已启用”，点击“确定”。
8. 重启电脑，设置生效。
✅ 方案 3：修改注册表（适合 Windows 家庭版）
家庭版没有组策略，但可通过注册表实现相同效果。
- 按
Win + R，输入regedit，打开注册表编辑器。 - 建议先备份注册表：点击“文件 → 导出”，保存备份。
- 定位到以下路径：
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
4. 在右侧找到或新建一个名为 LongPathsEnabled 的 DWORD 值，双击将其值设为 1（十六进制）。
5. 重启电脑，设置生效。
三、避坑指南：常见问题与注意事项
- 配置后仍报错？
检查路径是否超过 32767 字符。如果是，只能缩短路径，例如将仓库克隆到根目录（如D:\repo\）。 - 务必使用管理员权限
无论是配置 Git 还是修改注册表，请务必以管理员身份运行终端或编辑器，否则设置可能不生效。 - 团队协作建议
如果项目中有 Windows 用户，建议在 README 中说明需执行git config --global core.longpaths true，避免因路径问题影响协作。 - 临时应急
如果赶时间，可将仓库克隆到路径较短的目录（如E:\project），临时解决问题。
四、总结：一句话搞定“文件名过长”
遇到 Windows 下 Git 报 filename too long：
1. 先尝试执行：
git config --global core.longpaths true
（使用管理员权限的终端）
2. 重启终端或 IDE。
3. 若仍未解决，根据你的 Windows 版本使用组策略或注册表开启系统级长路径支持，并重启电脑。
这个问题本质上是 Windows 与现代项目结构之间的小摩擦。掌握了以上方法，下次再遇到就能轻松应对。
