核心摘要 (TL;DR)

• 问题现象：在 Windows 环境下执行 git add 等操作时，由于项目目录嵌套过深或文件绝对路径过长（通常超过260个字符），导致 Git 抛出 Filename too long 错误，无法将文件纳入版本控制。
• 根本原因：受限于 Windows 传统的 MAX_PATH 长度限制，且 Git for Windows 出于对旧版系统的兼容性考虑，默认关闭了长路径支持。
• 极速解法：直接在终端执行 git config --global core.longpaths true 开启 Git 全局长路径支持即可完美解决。

问题概览卡片

基本信息

• 问题分类：Git 核心配置 / Windows 文件系统兼容性
• 异常摘要：Filename too long 导致无法执行 git add
• 环境说明：
  • 操作系统：Windows 11 专业版 (Version 23H2)
  • 工具版本：Git for Windows 2.x.x
• 触发条件：在深层嵌套的目录结构中创建了具有描述性长文件名的文件。
• 报错摘要：error: unable to index file ... fatal: adding files failed

错误日志复现

1
2
3

error: open("<Root>/<Deep_Hierarchy>/<Long_Sub_Path>/<Desensitized_Filename>.md"): Filename too long
error: unable to index file '<Root>/<Deep_Hierarchy>/<Long_Sub_Path>/<Desensitized_Filename>.md'
fatal: adding files failed

1. 现象描述

在进行复杂的模块化开发或多代理架构设计时，目录深度往往会随着项目推进而增加。当某个文件的绝对路径长度（包含项目根目录路径）接近或超过 260 个字符时，Git 在执行索引（Indexing）操作时会因为触发操作系统的路径长度保护机制而报错。

即使在 Windows 资源管理器中能够正常查看或编辑该文件，Git 默认的兼容性设置也会阻止将其纳入版本控制。

2. 根本原因分析

1. Windows 历史局限性：传统 Windows API 受到 MAX_PATH 限制，定义最大路径长度为 260 个字符。
2. Git 默认行为：为了保持对旧版本 Windows 系统的兼容，Git for Windows 的 core.longpaths 参数在初始化时通常默认为 false。
3. 路径累加效应：路径长度 = 磁盘盘符路径 + 用户目录路径 + 项目根目录 + 文件夹嵌套层级 + 长文件名。在 Windows 环境下，由于用户目录路径通常较长，很容易在项目深度增加时触及上限。

3. 解决方案

方案一：修改 Git 全局配置（推荐）

这是最直接的解决方式，通过开启 Git 内部对长路径的支持，绕过 API 限制。

在终端执行：

1

git config --global core.longpaths true

配置验证：

1

git config --get core.longpaths

方案二：修改系统注册表（系统级支持）

如果其他开发工具（如 IDE 内置的 Git 插件）依然报错，可以开启系统级的长路径支持：

1. 快捷键 Win + R 输入 regedit。
2. 定位至：HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem。
3. 找到 LongPathsEnabled，将其值由 0 改为 1。

4. 预防与改进建议

• 缩减路径冗余：将项目存放于较浅的盘符目录下（例如 D:/dev/ 而非 C:/Users/Admin/Documents/Work/Projects/...）。
• 语义化缩写：在目录命名中使用标准缩写（如 Architecture 缩写为 arch），减少字符占用。
• 自动化环境检查：在团队协作的 README.md 中注明此配置项，或在项目初始化脚本中自动执行该配置。

5. 总结

通过开启 core.longpaths 配置，可以有效解决 Windows 平台下因文件路径过深导致的 Git 索引失败问题。这种规范化的卡片记录方式，旨在为复杂项目的环境搭建提供快速参考。