应运行git config --global core.longpaths true启用git长路径支持，因windows默认260字符路径限制与深层目录叠加导致检出失败，该配置需在克隆前设置才生效。
Git clone 报错 “Filename too long” 怎么办
Windows 默认启用的 NTFS 路径长度限制（260 字符）会和 Git 自动展开长分支名（如 feature/2024-q3/user-profile-refactor-with-async-validation-and-caching）叠加，导致子目录路径超出上限，git clone 或 git checkout 直接失败，报错信息通常是：error: unable to create file ...: Filename too long。
这不是 Git 本身的问题，而是 Windows 文件系统限制 + Git 默认不绕过该限制所致。解决核心是让 Git 允许创建超长路径 —— 但必须在 clone 前或 repo 初始化前开启，否则已存在的长路径文件不会自动修复。
- 运行
git config --system core.longpaths true（需管理员权限），全局生效 - 若无管理员权限，改用
git config --global core.longpaths true，只对当前用户有效 - 如果只是单个仓库要处理，进到空目录后先执行
git config core.longpaths true，再git clone - 注意：该配置仅影响后续操作，对已 checkout 出来的、已报错的目录无效；需删掉重来
checkout 时提示 “Pathspec 'xxx' did not match any files” 却明明有分支
这往往不是分支不存在，而是分支名含斜杠（/）且路径太长，导致 Git 在内部解析 ref 时因路径截断或缓存异常而“看不见”该分支。尤其在 Windows 上搭配旧版 Git（
验证方式：运行 git ls-remote --heads origin，能看到完整分支名列表；但 git branch -r 却不显示——说明本地 refs 数据库没正确同步长分支名。
- 先确保
core.longpaths已开启（见上一节） - 强制刷新远程分支索引：
git remote update origin --prune - 再试
git checkout -b feature/x origin/feature/x，显式指定远程 ref，避免依赖本地 branch cache - 避免用
git checkout feature/x这种简写，它依赖本地分支映射，而映射可能因路径问题失效
Git for Windows 的版本差异会影响 longpaths 行为
Git for Windows 2.30+ 默认启用 core.longpaths（通过调用 Windows 10+ 的 SetCurrentDirectoryW 和启用 long path API），但前提是系统本身也开了策略。低于 2.30 的版本即使设了 core.longpaths true，也可能因底层调用失败而静默降级。
检查方法：运行 git version，并确认 Windows 是否启用长路径支持：
- 打开组策略编辑器（
gpedit.msc），导航至「计算机配置 → 管理模板 → 系统 → 文件系统」，启用「启用 Win32 长路径」 - 或者在注册表中设置
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1 (DWORD) - Git for Windows 2.37+ 还引入了
core.filemode和core.autocrlf的默认值变更，建议统一升级到 2.39+ 版本以减少兼容性干扰
CI/CD 流水线里 clone 失败，怎么加兼容逻辑
流水线用的是干净容器，每次都是全新环境，core.longpaths 不会继承。不能靠手动配置，得在脚本里显式启用。
典型场景：GitHub Actions / GitLab CI 中 clone 私有仓库时失败。关键是在 git clone 前插入初始化步骤：
git config --global core.longpaths true git clone https://token@github.com/org/repo.git
注意两点：
- 不要用
--depth 1搭配core.longpaths—— 浅克隆可能跳过部分 ref，导致后续 checkout 长分支名失败 - 若使用自托管 runner（尤其是 Windows Server），还需确认系统级 long path 策略已启用，否则 Git 层面的配置无效
- 对于 Bitbucket 或 Azure Repos 等平台，同样适用；但 token 认证方式不同，需替换 URL 格式
长分支名本身不是 bug，但路径溢出是 Windows + Git 组合下的真实约束。真正容易被忽略的点是：配置必须在第一次 clone 前生效，且系统级支持不可跳过。换言之，光改 Git 配置，不碰 Windows 策略，等于只系了一半鞋带。
