MacOS系统韩文命名文件夹内执行git add单个文件报错求助

根因说明 #

这个问题本质是Mac文件系统的Unicode字符规范化差异导致的：

• Mac的APFS/HFS+文件系统存储非ASCII字符（比如韩文、带声调的拼音等）时，默认采用*NFD（Unicode规范分解形式）*编码
• 终端输入、Git默认的路径解析逻辑采用*NFC（Unicode规范组合形式）*编码

两种编码下的同一个韩文字符视觉表现完全一致，但底层字节序列不同，Git做路径校验时就会判定你输入的文件路径和仓库内实际存储的路径不匹配，触发「路径不在仓库内」的报错。而git add .是直接读取目录下的实际文件路径，不会经过终端输入的编码转换，所以可以正常执行。

可落地解决方案 #

方案1：全局配置Git适配Mac Unicode编码 #

执行以下命令开启全局适配，一次配置永久生效：

git config --global core.precomposeUnicode true

该配置会让Git自动把终端传入的NFC编码路径转换为和文件系统匹配的NFD编码，之后再执行git add 单个文件名即可正常识别韩文路径。

方案2：临时规避方法 #

如果不想修改全局配置，每次输入文件名时按Tab键自动补全路径即可：终端会自动读取文件系统实际的NFD编码路径填入，不需要手动输入，也能避免编码不匹配的问题。

方案3：手动转码添加 #

如果需要手动输入文件名，可通过iconv工具转码后执行添加操作，示例如下（假设要添加的文件名为테스트.md）：

git add "$(echo "테스트.md" | iconv -f utf-8-mac -t utf-8)"

内容的提问来源于stack exchange，提问作者SeongJung Kwon