Git里中文文件名变成SHA-1哈希一串乱码，这个问题说大不大，但卡住的时候确实让人一头雾水。明明git status里还好好显示着中文，怎么到了某个场景下就变成了一串看不懂的数字和字母？更常见的是git log或者git show --stat看提交时，文件名直接变成八进制编码，比如"\346\265\213\350\257\225.txt"，这种时候基本可以确定是Git的quotepath设置和系统的编码兼容出了问题。
这篇文章就把这个坑拆开讲透，内容包括：Git为什么在有些场景会显示SHA-1哈希、这个哈希到底代表什么、中文文件名乱码的真正成因是什么、怎么通过配置从根上解决，以及我在Windows和macOS两种环境下的踩坑记录。不管你是刚装好Git的新手，还是被这个问题困扰过的老手，这篇都值得花几分钟看完。
1. 先搞清楚Git到底怎么存文件名：为什么你会看到一串哈希
1.1 SHA-1哈希是什么，Git凭什么用一串数字代替文件名
很多人在命令行里执行git log --follow，或者在GitLab/GitHub网页端看到一串40位的十六进制字符串，第一反应是“文件名怎么被替换了”。其实这不叫替换，这是Git的内容寻址机制在正常工作。
Git内部不是按文件名存文件的。你把一个文件提交进去的时候，Git会先读取文件内容，对内容做一次SHA-1哈希运算，得到一个40位的十六进制字符串，例如e69de29bb2d1d6434b8b29ae775ad8c2e48c5391。这个哈希值就是文件内容的“身份证号”，Git用这个身份证号把文件内容存进对象库（.git/objects目录下）。
那你可能会问：既然内容不按文件名存，那Git怎么知道这个文件叫什么、在哪个目录？答案在tree对象里。一次提交会产生三类对象：
- blob对象：存的是文件内容，文件名不在这里面。
- tree对象：存的是目录结构，包括每个子目录和文件的名字，以及它们对应的blob对象哈希值。
- commit对象：记录提交信息、作者、时间，以及指向某个tree对象的哈希值。
所以GIT显示SHA-1哈希的场景，本质是它把“某个对象”的哈希值展示给你看了，而不是把文件名弄丢了。比如git rev-parse HEAD输出的是commit对象的哈希，git ls-files --stage输出的是blob对象的哈希和路径，这两个场景都会出现一串看起来很吓人的40位字符串。
这里有一个非常重要的理解：只要文件内容完全一样，不管文件名是什么，生成的blob哈希都是一样的。这也是Git能高效做内容去重和快速比较版本差异的根本原因。而文件名的变化，只体现在tree对象的记录里，不会改变blob哈希。
1.2 中文文件名乱码的根因：编码不一致和quotepath设置
Git能正常处理中文文件名，但显示层出了问题，常见的原因有两个。
第一个原因是终端或系统默认编码不是UTF-8。Windows的中国大陆版本，系统默认的编码是GBK（代码页936），而Git内部统一使用UTF-8处理文件名和提交信息。当Git把UTF-8字节流交给终端去显示，终端却用GBK去解码，自然就乱成一团。macOS和Linux默认就是UTF-8，所以在这两个平台上遇到中文乱码的概率会小很多。
第二个原因是Git的一个保护机制，叫core.quotepath。这个配置默认是true，作用是：对于非ASCII字符（包括中文、日文、韩文等），Git在输出路径时会把它们转义成八进制格式。比如中文文件测试.txt，在git status里会显示成：
"\346\265\213\350\257\225.txt"这一串八进制数字就是UTF-8编码下“测试”两个字的字节流。Git这样做是为了防止某些不支持UTF-8的终端把输出搞坏，但代价就是人眼完全看不懂。把core.quotepath设置成false，Git就会直接输出原始的中文字符，在支持UTF-8的终端里就能正常显示了。
所以“中文文件名乱码”和“看到SHA-1哈希”其实是两个耦合在一起的现象：
- 看到SHA-1哈希，是因为你查看的对象本来就是个哈希（blob、tree、commit），不是文件名。
- 看到乱码，是因为
core.quotepath默认转义，或者终端编码与Git的UTF-8不匹配。
两者同时出现的最典型场景，就是用git log --name-only或者git show --stat查看提交中涉及的文件。Git会把文件名和对象哈希一起输出，文件名被转义成八进制，对象名直接显示哈希，合起来就是你看到的“文件名乱码+SHA-1哈希”叠buff现场。
2. 环境准备与核心配置：先把底子打好
2.1 确认Git版本和当前配置
再好的方案也得先知道自己的环境是什么状态。命令行分别执行下面几条命令，先摸个底：
git --version git config --global --list第一条查看Git版本。第二条会列出用户级的全部配置，重点关注user.name、user.email、core.quotepath、i18n.commitEncoding这几个键值。如果第二条命令提示没有任何输出，说明你还没配置过用户级参数，后面用git config --global设置的时候会一并写入。
不同版本的Git对中文和Unicode的处理细节有差异。我实测下来，Git 2.20以上版本对UTF-8的支持已经非常完善，建议至少保证Git版本在2.20以上。Windows环境建议直接装Git for Windows官方版本，它自带的Git Bash终端对UTF-8支持得比较好，比在CMD或PowerShell里强很多。
另一个容易忽略的点是操作系统的区域语言设置。Windows下如果“非Unicode程序的语言”没设置成“中文（简体，中国）”或者没勾选“Beta版：使用Unicode UTF-8提供全球语言支持”，即使Git配置全对，某些外部工具还是会把GBK当作默认编码读文件，导致乱码。
2.2 三条核心配置命令：从根上解决90%的乱码
针对中文文件名乱码和SHA-1显示问题，我建议直接执行下面三行配置，一步到位：
git config --global core.quotepath false git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8逐条解释一下作用：
core.quotepath false：关闭Git对非ASCII路径的八进制转义。配置之后，git status、git log --name-only、git show --stat等命令输出的中文文件名会直接显示原始字符。i18n.commitEncoding utf-8：告诉Git，提交信息（commit message）本身是用UTF-8编码的，Git在写入和读取提交信息时按UTF-8处理。这一步能避免在部分Windows环境下提交中文备注变成乱码。i18n.logOutputEncoding utf-8：控制Git在输出日志时，将内部的提交信息以UTF-8编码输出到终端。如果你的终端本身就是UTF-8，这条配置效果不明显，但在GBK终端下能起到转码作用。
如果你用的是macOS，还有一个容易被忽略的配置：
git config --global core.precomposeunicode truemacOS的文件系统（APFS/HFS+）在存储文件名时使用NFC规范化形式，而Git默认可能会按NFD处理。如果你在macOS上发现某些中文文件名在Git里显示成两个字符，比如“é”这种拆开的，执行这条配置可以解决。
2.3 Windows终端编码切换：让CMD和PowerShell听懂UTF-8
Git配置完成后，如果终端本身还是GBK解码，输出照样乱。Windows下我的建议是：
- 优先使用Git Bash，它在启动时已经设置好UTF-8环境，基本不用额外操作。
- 如果在CMD里跑Git命令，先执行
chcp 65001切换到UTF-8代码页，然后再执行Git命令。 - 如果在PowerShell里跑，Windows 10以上版本可以先把控制台字体改成“TrueType字体（如Consolas或YaHei Consolas）”，然后执行
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8临时切换，或者直接改注册表让PowerShell默认使用UTF-8。
我自己在Windows上折腾过很长一段时间，最后的结论是：与其跟CMD和PowerShell的代码页搏斗，不如直接用Git Bash。Git Bash是一个模拟Unix终端的程序，UTF-8是它的天然环境，中文文件名和提交信息在Git Bash里基本不会出乱码。这不是逃避，而是选择最稳定的工具。
3. 实操过程：从乱码到正常显示的完整流程
3.1 场景重现：中文文件名在status/log/diff中的乱码表现
先看一个最典型的乱码现场。假设仓库里有一个文件叫测试文件.txt，内容改动后执行git status，如果core.quotepath还是默认的true，输出是这样的：
$ git status On branch main Changes not staged for commit: (use "git add <file>..." to update what will be committed) modified: "\346\265\213\350\257\225\346\226\207\344\273\266.txt"然后执行git log --oneline --name-only看看历史提交，输出会变成：
abc1234 (HEAD -> main) update test file "\346\265\213\350\257\225\346\226\207\344\273\266.txt"你既看不到“测试文件”这几个字，只能看到一串八进制+文件名混合体。如果提交历史较长，会进一步看到每个提交对应一个或多个文件名，旁边并显示相关的哈希值（比如提交哈希）。这正是标题里“中文文件名乱码显示SHA-1哈希值”的典型组合。
执行git config --global core.quotepath false之后，再次运行同样的命令，输出变为：
$ git status On branch main Changes not staged for commit: (use "git add <file>..." to update what will be committed) modified: 测试文件.txt中文正常显示，SHA-1哈希也不会再跟文件名混在一起。因为这时候Git只是关闭了路径转义，并没有改变底层存储结构，所以文件本身的内容、历史、哈希都不会受影响。
3.2 修复一个已有仓库：文件改名、提交历史与哈希的关系
如果你已经在乱码状态下提交了好几个版本，现在配置改好了，文件会正常显示，但历史上那些提交里的路径还是转义状态吗？
答案是不需要修复。因为Git对象库里存的路径是原始字节，转义只是显示层的处理。core.quotepath false只是在输出时不再转义，底层字节没变，所以以前的历史提交在配置修复后也能正常显示中文文件名。这个我是实测过的，放心用。
如果历史提交里的文件名本身就存错了（比如当时用的工具把文件名写成了乱码字节），那就需要改写了。这种情况比较麻烦，常见的做法有两种：
第一种，用git mv把“乱码名”改成正确的名字：
git mv "\346\265\213\350\257\225.txt" 测试文件.txt git commit -m "rename file to correct Chinese name"注意：git mv右边的目标路径直接用中文没问题，但左边的源路径如果终端不能正常输入那串八进制，可以在Git Bash里用通配符或者Tab补全来避免打错。执行完成后，Git会把这次改名当成一次rename事件记录，历史里的旧blob对象依然存在，但新的提交已经指向正确路径。
第二种，用git filter-repo批量改历史。如果乱码文件名在几十个提交里反复出现，并且你的团队能接受改写历史（需要强制推送并且通知所有人重新克隆），可以写一个--filename-callback脚本处理。但说实话，个人项目或者小团队项目我不推荐轻易改写历史，风险高收益低。只要从现在开始配置正确，以后提交不再产生新的乱码，历史里的旧文件名顶多影响检索美观，不影响代码正确性。
3.3 新仓库的标准操作流程：从init到第一次提交
如果你刚新建一个仓库，强烈建议按下面的顺序操作，一步到位避免后续踩坑：
- 先设置全局配置：
git config --global core.quotepath false git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8- 初始化仓库：
git init如果仓库目录下已经有中文文件名，先执行
git status确认显示是否正常。如果正常，说明配置生效了。如果不正常，多半是终端编码问题，先切换到Git Bash或用chcp切代码页。添加文件并提交：
git add . git commit -m "初始化项目，含中文文件名"- 用
git log --oneline --name-only验证输出。正常情况下中文文件名直接显示，提交哈希和文件名各归各，不再混在一起。
这一套流程走下来，你后面的所有操作都会很干净。这里也想多说一句，团队协作时最好把这三条配置写进团队的文档或初始化脚本里，让每个新成员clone代码前先执行一遍，能省掉大量来回问“为什么我这边乱码”的沟通成本。
4. 常见问题与排查技巧实录
4.1 典型问题速查表
这部分把我这些年遇到的各种乱码问题整理成了一张表，每一条都是真实踩过的坑，不是网上随便抄的。
| 问题现象 | 根本原因 | 解决办法 |
|---|---|---|
git status显示"\346\265\213\350\257\225.txt" | core.quotepath默认值为true | 执行git config --global core.quotepath false |
git log里提交信息乱码（中文备注变问号） | 提交信息编码与显示终端编码不一致 | 设置i18n.commitEncoding和i18n.logOutputEncoding为utf-8，并在终端里用UTF-8 |
| Windows的CMD里中文变成菱形问号 | CMD默认代码页936（GBK），与UTF-8不匹配 | 执行chcp 65001切换UTF-8代码页，或改用Git Bash |
| GitHub网页端显示中文文件名正常，本地乱码 | 本地终端编码问题 | 检查操作系统区域语言设置，在Windows设置里勾选UTF-8 Beta选项 |
| macOS下文件名拆成两个字符 | NFD与NFC规范化不一致 | 设置core.precomposeunicode true |
git diff输出中文件名乱码，但内容正常 | 同样受core.quotepath影响 | 关闭quotepath后重新看diff |
| 仓库里文件名在Windows上看正常，在Linux上乱码 | 文件系统编码差异或历史提交时的工具转码 | 统一策略：强制全仓库使用UTF-8文件名和提交信息 |
4.2 排查思路：先定位是Git还是终端的问题
如果你遇到的乱码现象不在上表里，可以按这套思路排查：
第一步，判断是不是Git配置问题。执行git config --global --list看core.quotepath和i18n相关项是否存在、值是否正确。如果core.quotepath是true，那乱码九成是它造成的。
第二步，判断是不是终端问题。用Git Bash执行同样的命令，如果Git Bash里正常而CMD/PowerShell里乱码，说明Git配置没问题，是终端编码不对，按上面2.3节的方法切换代码页。
第三步，判断是不是文件系统问题。在纯ASCII路径下新建一个文件（比如test.txt），如果这个文件在git status里显示正常，而言中文文件乱码，说明问题出在非ASCII字符处理上；如果所有文件都乱，先检查Git环境变量LANG和LC_ALL是否设置成en_US.UTF-8或zh_CN.UTF-8。
第四步，用git ls-files --stage直接看索引里存的路径是什么。这个命令会输出路径对应的blob哈希和文件路径，如果路径里是中文显示正常，说明Git索引层没问题，输出层有问题；如果路径本身乱码，那可能是在添加文件时文件名就已经存错了。
4.3 实测经验：Windows、macOS、Linux三平台的差异
三个平台我都长期用Git配合中文文件名，结论差异挺大。
Windows是最容易出问题的平台，核心原因在于系统默认编码不是UTF-8，加上终端工具链五花八门。我的经验是：装Git for Windows时，安装向导里有一步“Adjusting your PATH environment”和“Choosing the default behavior of git pull”，这两步都选默认推荐项就好，不用动。真正影响中文的是“Configuring the line ending conversions”那一步，建议选“Checkout as-is, commit as-is”，避免自动转换换行符时干预文件内容。
macOS平台的问题集中在文件名Unicode规范化。你可以先用git config --global core.precomposeunicode true解决大部分问题。如果某些文件已经被NFD形式提交了，可以在仓库里用git mv改名来触发重写。
Linux平台其实最省心，因为终端和文件系统基本都是UTF-8，只要确认locale设置正确，中文文件名在Git里基本不会出问题。但有一种情况例外：你从一个Windows同事那里克隆了一个仓库，而那个同事用GBK编码或者错误的工具提交过文件，历史里可能残留乱码文件名。这种情况建议不要用脚本批量改写历史，而是用git mv逐一把当前版本的文件名改对，从当下开始保持干净。
4.4 那些不推荐的做法和容易被误解的点
关于“中文文件名乱码显示SHA-1哈希”，网上有些说法不准确，我在这里澄清几个常见误解。
第一，“把core.quotepath设为false会破坏仓库”。这个说法纯属多虑。core.quotepath只影响Git输出路径时的显示形式，不改变对象库里的任何字节，也不会影响文件内容哈希。你关掉它，仓库依然安全。
第二，“中文文件名会导致Git性能下降”。理论上Git在计算SHA-1哈希时只处理内容，不处理文件名，所以文件名是中文还是英文，对哈希计算性能没有任何影响。真正有影响的是路径比较，但这个代价微乎其微，不用在意。
第三，“使用中文文件名会让仓库无法跨平台”。这是很多团队拒绝中文文件名的核心理由，但说实话，现代Git配合UTF-8已经能跨平台处理中文文件名。真正容易出问题的场景是旧版工具链或者没有统一编码规范。如果团队对中文文件名没有硬性禁止，完全可以用；如果团队有规范，那就遵守规范，这不属于技术问题。
第四，也是最容易被误解的一点：Git显示SHA-1哈希并不意味着文件“损坏”或者“丢失”。哈希就是Git内部的对象ID，你日常看到的很多输出（如git log的提交哈希、git ls-files的blob哈希）本来就该显示哈希。需要区分的是“文件名乱码”和“哈希值正常显示”是两个独立问题，不要混为一谈。
5. 进阶技巧：让Git输出更清晰的一些小配置
5.1 和文件名显示相关的其他配置
除了前面那三条核心配置，还有几个配置可以进一步优化Git在中文环境下的使用体验。
git config --global core.untrackedCache true：启用未跟踪文件缓存，在有大量文件的仓库里，git status速度会明显提升。这个配置本质上跟中文文件名关系不大，但能减少等待时间，间接提升体验。
git config --global status.showUntrackedFiles all：让git status显示所有未跟踪文件，而不是只显示目录。在排查中文文件名改动时更直观。
git config --global alias.st status、alias.lg "log --graph --oneline --decorate --all：配置Git别名，把常用命令缩短。这个见仁见智，我能说的是：配置了别名以后，我几乎不再手打完整的git log --oneline --graph了，效率提升非常明显。
5.2 工具链配合：VS Code、SourceTree、TortoiseGit的中文支持
命令行只是Git的一种使用方式，如果你用GUI工具，中文文件名乱码的现象和解决办法又不太一样。
VS Code的源代码管理面板，默认使用UTF-8读取Git输出，配合core.quotepath false，中文文件名基本直接正常显示。如果发现VS Code里还是乱码，去设置里搜索files.encoding，确认是utf8。
SourceTree里如果中文文件名显示异常，可以检查仓库设置里的“文字编码”选项，手动设为UTF-8。SourceTree自己的日志输出控件对Unicode支持稍弱，但大部分中文字符都能正常显示。
TortoiseGit是Windows老牌Git GUI，它继承了很多Windows传统控件，中文文件名的显示依赖系统区域设置。在系统区域语言设置里勾选“使用UTF-8提供全球语言支持”之后，TortoiseGit的中文显示会稳定很多。
5.3 团队协作时的统一策略：从源头减少编码冲突
个人项目怎么配置都行，但团队协作时必须统一策略。我参与过几个有严格代码规范的项目，Git中文文件名这一块通常是这样约定的：
- 所有成员统一使用UTF-8编码提交，禁止在配置文件里手动指定GBK或其他编码。
- 所有成员执行
git config --global core.quotepath false。 - 不使用系统自带的记事本编辑
commit message（Windows记事本默认ANSI编码，容易把中文注释存成GBK），改用VS Code或Sublime Text打开，并确保编辑器状态栏显示UTF-8。 - 如果实在避免不了使用中文文件名，保持文件名简短，避免包含空格和特殊符号（如
#、%、&），这些符号在某些终端和工具链里会引发额外的问题。
这套约定并不能百分之百保证所有工具都完美适配，但能把出现乱码的概率降到最低。毕竟Git本身不关心你的文件名是中文还是英文，它只关心字节流是否正确；出问题的大多是链路里的某个“翻译官”没干好活。
6. 写在最后的一点经验
这篇文章讲了Git中文文件名乱码和SHA-1哈希显示的来龙去脉，核心其实就两件事：理解Git底层是内容寻址的，文件名和内容是分开存储的；再就是通过core.quotepath false和统一UTF-8编码来解决显示层的问题。
我个人用Git处理中文文件名的经验是：提前配置永远比事后修复省力。新装一台电脑，第一件事就是把core.quotepath false和三条UTF-8配置写进全局配置，后面几乎不会再遇到乱码。如果已经踩了坑，也别慌，按文章第三节的方法检查配置、切换终端，基本几分钟就能解决。
最后再分享一个小技巧：如果你在一个大仓库里执行git log --all --name-only时被一堆哈希和乱码文件名刷屏，可以加一个--pretty=format:"%h %s"参数，把输出格式压缩成“短哈希+提交说明”两列，然后在第二列再配合--name-only查看具体文件。这样输出会比默认排版清爽很多，排查问题时眼睛不会太累。好的工具和好的配置，配合好的使用习惯，才能真正让你的工作流顺畅起来。
