解决 Git 中文乱码问题：从乱码到完美显示

!https://git-scm.com/images/logos/downloads/Git-Icon-1788C.png

问题现象

在使用 Git 进行版本控制时，你是否遇到过这些令人头疼的中文乱码问题？

# 文件名显示乱码
$ git status
?? "\345\244\247\345\255\230.txt"

# 提交信息显示乱码
$ git log
commit 1234567890abcdef
Author: \344\270\211\346\234\254 <[email protected]>
Date:   Mon Jan 1 12:00:00 2024 +0800

    \350\217\234\345\215\225\344\270\212\347\224\250\346\210\267\346\226\207\344\273\266

# 分支名显示乱码
$ git branch
* \345\275\223\345\205\245/\346\265\201\350\257\225
  main

这些乱码不仅影响工作效率，还可能导致误操作。本文将系统性地解决 Git 中文乱码问题。

问题根源分析

Git 中文乱码主要由以下原因导致：

  1. 字符编码不统一：Git 内部使用 UTF-8，但终端/系统可能使用 GBK/GB2312
  2. 配置参数缺失：未正确设置 Git 的字符编码相关配置
  3. 系统环境差异：Windows、macOS、Linux 处理方式不同
  4. 历史遗留问题：旧版本 Git 对 Unicode 支持不完善

完整解决方案

第一步：检查当前 Git 配置

# 查看所有 Git 配置
git config --list

# 重点检查以下配置项
git config --global core.quotepath
git config --global i18n.commitencoding
git config --global i18n.logoutputencoding

第二步：基础配置修复

# 1. 设置不转义非 ASCII 字符
git config --global core.quotepath false

# 2. 设置提交信息编码为 UTF-8
git config --global i18n.commitencoding utf-8

# 3. 设置日志输出编码为 UTF-8
git config --global i18n.logoutputencoding utf-8

# 4. 设置默认文本编辑器（可选，推荐 VS Code）
git config --global core.editor "code --wait"

第三步：系统级环境配置

# 设置终端编码为 UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# 将配置写入 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）
echo 'export LANG=en_US.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.bashrc
source ~/.bashrc

第四步：针对不同系统的特殊处理

Windows 系统

# 1. 设置 Git Bash 使用 UTF-8
git config --global core.quotepath false
git config --global gui.encoding utf-8
git config --global i18n.commitencoding utf-8
git config --global i18n.logoutputencoding utf-8

# 2. 修改 Windows 区域设置
# 控制面板 → 区域 → 管理 → 更改系统区域设置 → 勾选"Beta: 使用 Unicode UTF-8 提供全球语言支持"

macOS 系统

# 1. 检查终端编码
# 终端 → 偏好设置 → 描述文件 → 高级 → 文本编码选择"Unicode (UTF-8)"

# 2. 设置 Git 配置
git config --global core.quotepath off
git config --global http.postBuffer 1048576000

Linux 系统

# 1. 安装中文字体（如文泉驿）
sudo apt install fonts-wqy-microhei

# 2. 设置系统 locale
sudo locale-gen zh_CN.UTF-8
sudo update-locale LANG=zh_CN.UTF-8

高级场景处理

场景 1：已存在乱码的历史记录

# 1. 克隆仓库时指定编码
git clone -c i18n.logoutputencoding=utf-8 <repository-url>

# 2. 批量重命名已乱码的文件
# 使用工具如 convmv 转换文件名编码
sudo apt install convmv
convmv -f gbk -t utf-8 --notest -r .

场景 2：与 Windows 协作开发

# 1. 在 .gitattributes 文件中添加
*.txt text eol=lf
*.md text eol=lf
*.py text eol=lf
*.js text eol=lf
*.css text eol=lf
*.html text eol=lf

# 2. 设置自动转换换行符
git config --global core.autocrlf input  # Linux/macOS
git config --global core.autocrlf true   # Windows

场景 3：IDE 集成问题

IDE配置方法
VS Code设置 "files.encoding": "utf8" 和 "git.defaultEncoding": "utf8"
IntelliJFile → Settings → Editor → File Encodings → 全部设为 UTF-8
EclipseWindow → Preferences → General → Workspace → Text file encoding → UTF-8

常见问题排查

问题现象可能原因解决方案
仅部分文件乱码文件本身编码不是 UTF-8使用 iconv 转换文件编码
提交信息乱码编辑器编码设置问题检查并统一编辑器编码为 UTF-8
推送后远程仓库显示乱码远程服务器编码设置问题联系服务器管理员设置 locale 为 UTF-8
合并冲突时乱码比较工具编码问题更换支持 UTF-8 的比较工具（如 Meld）

预防措施

  1. 项目初始化时设置

    # 创建 .gitattributes 文件
echo "* text=auto" > .gitattributes
echo "*.txt text" >> .gitattributes
echo "*.md text" >> .gitattributes
git add .gitattributes
git commit -m "Add .gitattributes for encoding"

  2. 团队规范

    • 统一使用 UTF-8 编码
    • 统一使用 LF 换行符
    • 在 README 中注明编码要求

  3. CI/CD 环境配置

    # GitHub Actions 示例
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Set up locale
        run: |
          sudo locale-gen zh_CN.UTF-8
          export LANG=zh_CN.UTF-8

验证修复结果

# 1. 创建一个测试文件
echo "这是一个测试文件" > 测试文件.txt

# 2. 添加到暂存区
git add 测试文件.txt

# 3. 查看状态
git status
# 应该显示：new file:   测试文件.txt

# 4. 提交
git commit -m "测试中文提交信息"

# 5. 查看日志
git log --oneline
# 应该正确显示中文提交信息

结语

Git 中文乱码问题虽然常见，但通过系统性的配置可以彻底解决。关键步骤总结：

  1. 设置 core.quotepath false 防止路径转义
  2. 统一使用 UTF-8 编码
  3. 根据操作系统进行针对性配置
  4. 建立团队编码规范
💡 专业建议：在项目根目录创建 .gitattributes 文件，可以一劳永逸地解决大部分编码问题，特别适合团队协作场景。

修复完成后，你将获得一个清爽的 Git 工作环境，中文显示完美无缺，再也不用为乱码而烦恼！