长路径问题是什么
Windows 默认的路径长度限制（约 260 字符）会让深层目录的检出失败，Git 报错 Filename too long，最常出现在嵌套 node_modules、多层子模块与大仓库存档场景。Git 提供 core.longpaths=true 开关，但它要与系统侧的长路径策略（LongPathsEnabled）配合才生效；忽略任一侧，问题都会原样复现。分清「Git 配置」与「系统策略」两层，是排错的第一步。
基本信息
| Git 配置 | git config --global core.longpaths true |
|---|---|
| 系统策略 | Windows LongPathsEnabled 需开启（Win10 1607+ 支持） |
| 典型报错 | Filename too long（clone、checkout、检出深层目录时） |
| 影响场景 | 深层 node_modules、子模块嵌套、超长归档目录 |
| 生效范围 | 仅 Git 自身操作；编辑器与打包工具需各自支持 |
| 排查顺序 | 先确认报错进程，再分别核对 Git 配置与系统策略 |
典型使用场景
- 前端仓库检出：node_modules 依赖层级深，安装依赖时最先撞限
- 子模块嵌套：多层子模块路径叠加，递归克隆时直接失败
- 归档导出：目录名叠加日期与版本号后超过限制
- Windows CI runner：流水线检出同样受限，配置要写入初始化脚本
- 混合工具链：Git 放开后，编辑器与压缩工具是否支持要单独验证
常用示例
常用示例
git config --global core.longpaths true # Git 侧放开长路径使用
git config --global --get core.longpaths # 复核配置是否写入
git --version # 确认版本，老版本行为可能有差异
# 系统侧：注册表 LongPathsEnabled 设为 1（Win10 1607+），改后重开程序验证
git clone --recursive https://example.com/repo.git # 用小目录先验证再上大仓库两层配置对照
| 层级 | 配置项 | 作用 |
|---|---|---|
| Git | core.longpaths | 让 Git 自身使用长路径方式访问文件 |
| 系统 | LongPathsEnabled | 允许进程使用超过限制的路径 |
| 应用 | 各自开关 | 编辑器、打包与解压工具需自身支持 |
| CI | 初始化脚本 | runner 上同样要落实两层配置 |
企业镜像或旧工具链可能不感知长路径，遇到混合环境时先在小目录验证，再铺开到主仓库。
core.longpaths 只影响 Git 自己；安装脚本、压缩工具等超长路径报错时要单独处理，构建脚本尽量从浅目录开始。
系统策略是整机级变更：规范环境建议走变更流程评估，再开启 LongPathsEnabled。