前两天有个刚入职的同事在群里喊“我明明提交了代码为什么代码评审系统里看不到我的提交记录”远程看了一眼他第一次用Git提交之前完全没配置过user.name和user.email于是在那台机器上所有commit的作者信息全都变成了unknown。这个场景太经典了。如果你也在用Git或者刚装好Git准备提交第一个项目那么“Git配置用户名与邮箱”这件事就是你绕不开的第一步。它决定了你每一次提交记录上写的是谁的名字、挂的是哪个邮箱也直接影响代码托管平台的贡献图、代码评审关联、甚至团队里的责任追溯。这篇内容会从原理讲到实操覆盖第一次配置、多账号隔离、常见坑排查以及团队协作中的身份规范。无论你是刚接触Git的初学者还是被提交作者信息坑过一次的老手都能在这里找到可以直接照抄的配置方案。1. 为什么每次提交都要带着名字——Git身份配置的核心逻辑1.1 一条commit背后藏着哪些身份信息Git里每次提交都会同时记录两组身份信息author作者和committer提交者。前一个是指“这段代码是谁写的”后一个是指“这次提交是谁执行的”。大多数情况下两者是同一个人所以很多人没注意到它们其实是独立字段。你可以用下面的命令看到一次提交里的完整身份信息git log -1 --formatauthor: %an %ae%ncommitter: %cn %ce输出大概长这样author: Zhang San zhangsanexample.com committer: Zhang San zhangsanexample.com其中%an是作者姓名%ae是作者邮箱%cn是提交者姓名%ce是提交者邮箱。很多人只关心“代码能不能push上去”但恰恰忽略了这些元数据。一旦身份没配置好后面代码评审、git blame追溯、贡献图统计全都对不上号。Git的设计哲学是分布式的允许你在完全没有网络、没有中央服务器的环境下提交代码。这就意味着Git没法在你提交的时候去某个在线平台校验“你是谁”它只能信任你本地的配置。所以身份配置不是可选项而是每次提交前必须准备的基础信息。1.2 三级配置体系system、global、localGit的配置分为三个层级优先级从低到高分别是system系统级、global全局级、local仓库级。高优先级会覆盖低优先级。配置级别配置文件位置作用范围使用场景systemGit安装目录下的etc/gitconfig这台机器上的所有用户服务器镜像、统一装机环境global用户主目录下的~/.gitconfig当前系统用户的所有仓库个人电脑的默认身份local仓库目录下的.git/config当前这一个仓库不同项目使用不同身份这里可以打个比方system像公司统一规定所有人默认必须遵守global像部门内部惯例大多数情况下适用local像项目组自己立的规矩某个项目特事特办。实际使用时绝大多数人只需要配置global只有需要在一台电脑上切换多个身份时才需要动local。查看当前生效的完整配置推荐用这条命令git config --list --show-origin加了--show-origin之后不仅能看到配置项的值还能看到这个值来自哪个文件。这在排查“明明改了却不生效”的时候非常有用。2. 从零开始第一次配置用户名与邮箱的正确姿势2.1 安装Git后先做这三件事新机器装好Git我建议按顺序做三件事。第一件确认Git版本第二件配置全局身份第三件验证配置。确认版本很简单git --version接着设置你的名字和邮箱git config --global user.name Zhang San git config --global user.email zhangsanexample.com注意user.name这里填的是“展示名”不是登录用户名。Git官方建议用真实姓名方便团队成员识别。如果你比较在意隐私用昵称也可以但要保持稳定。不要今天用zs明天用zhangsan2024否则别人在代码评审里根本认不出你。邮箱部分我强烈建议填一个真实、常用、能正常收信的邮箱。因为很多代码托管平台会通过提交邮箱关联你的账号头像和贡献记录如果你随手编了一个12345qq.com或者testtest.com轻则贡献图不亮重则评审系统无法创建正确账号。这里补充一个重要区分Git配置邮箱不涉及邮箱密码、端口、授权码等任何与邮件收发有关的信息。它只是把邮箱当作一个字符串写进提交记录里。真正推送代码时需要的认证凭据是代码平台自己的Token或SSH密钥跟邮箱授权码完全是两码事。2.2 验证配置是否真的生效配置完之后不要急着提交代码先花十秒钟验证一遍。查看全局配置git config --global --list查看“当前仓库实际生效的身份”注意不加--globalgit config user.name git config user.email如果你想确认这个值到底来自哪个配置文件用之前提到的命令git config --list --show-origin它会输出类似这样的内容file:/home/zhangsan/.gitconfig user.nameZhang San file:/home/zhangsan/.gitconfig user.emailzhangsanexample.com如果看到file:.git/config说明你正在使用仓库级配置如果看到file:/home/xxx/.gitconfig说明走的是全局配置。这一步能帮你判断自己到底有没有改对地方。还有一个更实用的命令可以直接看到“一次新提交实际会使用的作者身份”git var GIT_AUTHOR_IDENT输出类似Zhang San zhangsanexample.com 1700000000 0800这个命令会把环境变量、配置文件、平台特定设置全部汇总后给出最终结果。如果你改了配置却总觉得没生效先跑这条命令基本能定位问题。2.3 中文用户名、中文路径这些幺蛾子怎么处理关于user.name能不能用中文答案是能Git本身完全支持UTF-8编码。但我不太建议在开源项目或跨国协作的仓库里用中文名因为很多第三方工具、CI系统、代码评审插件对非ASCII字符的兼容性参差不齐。轻则显示乱码重则导致脚本解析失败。比如你提交了中文作者名在某些老旧的Web评审系统里可能显示成?UTF-8?Q?E5BCA0E4B889?这种编码乱码。这种情况并不是Git的问题而是上游系统不支持UTF-8。稳妥的做法是个人项目随意公开项目用拼音或英文名。还有一类经典问题跟中文路径有关。比如Windows用户名是中文导致C:\Users\张三\这个路径下有特殊字符。老版本的Git在读取~/.gitconfig的时候如果编码处理不当可能报错或者读不到配置。遇到这种情况可以先检查Git版本尽量升级到最新版。另外很多人在Windows上遇到git status显示中文文件名变成\345\274\240\344\270\211这种八进制转义这个不是作者名问题而是core.quotepath的默认行为。可以在全局配置里关掉转义git config --global core.quotepath false这样中文文件名会直接显示成可读的中文看起来清爽很多。它和用户名的中文问题是两回事但都属于“中文环境使用Git”的常见痛点一并解决掉。3. 多账号场景一台电脑如何优雅管理GitHub、Gitee、GitLab3.1 为什么不能用一套global配置走天下很多人一台电脑上既要访问公司的GitLab又要用GitHub传开源项目可能还会用Gitee备份仓库。如果一开始图省事只配置了一套全局用户名和邮箱后面就会遇到一个常见尴尬用个人邮箱提交了公司项目或者用公司邮箱提交了个人开源代码。代码托管平台判断“这个提交是谁的”主要依据是提交邮箱。如果公司GitLab邮箱绑定了企业账号而你提交时用了个人邮箱平台上就会显示成一个陌生账号你的提交记录和评审记录全部分散。反之也是一样。所以多账号场景下正确思路是“按仓库切换身份”而不是“一套身份走天下”。3.2 local配置仓库级身份隔离最简单的切换方式是在进入某个仓库后执行不带--global的git config命令cd /path/to/company-project git config user.name Zhang San (Company) git config user.email zhangsancompany.com这个配置会写入当前仓库的.git/config文件只对这个仓库生效不影响其他任何项目。顺序是进入仓库目录 - 设置local身份 - 提交代码。验证方式git config --local --list你会看到当前仓库的配置项。local的优先级高于global所以只要在某个仓库里设置了local它就会自动覆盖全局值。这里要注意一点.git目录是仓库的内部管理目录不会被版本控制所以local配置不会随着仓库push到远端也不会被其他人看到不需要担心个人信息泄露。3.3 SSH密钥和用户名邮箱是一回事吗这可能是新手最容易混淆的概念。SSH密钥解决的是“你有没有权限推送”而user.name和user.email解决的是“这次提交记录上挂谁的名字”。两者完全是两个层面的事情。代码托管平台的commit页面显示谁依据的是提交里的邮箱不是SSH密钥。哪怕你推送时用的是公司配置的SSH密钥只要提交记录里的邮箱是个人邮箱平台上照样显示个人账号。反过来也一样。所以不要以为“我SSH密钥配好了提交记录就自动正确”。SSH密钥只负责认证传输通道提交里的身份必须靠Git配置来保证。如果你需要严格区分公司和个人场景还可以在~/.ssh/config里给不同平台配置不同的SSH密钥别名但这不影响user.name和user.email的配置逻辑。核心原则仍然是一个仓库对应一套身份配置。3.4 进阶玩法includeIf按目录自动切换身份如果每次进入仓库都要手动设置一遍local配置多个项目来回切换时很麻烦。Git 2.13及以上版本提供了一个更优雅的方案includeIf。原理很简单根据仓库路径自动加载不同的配置文件。比如你约定公司项目统一放在~/work/目录下个人项目统一放在~/personal/目录下那么在~/.gitconfig里可以做如下配置[includeIf gitdir:~/work/] path ~/.gitconfig-work [includeIf gitdir:~/personal/] path ~/.gitconfig-personal然后创建两个独立的身份文件。~/.gitconfig-work内容[user] name Zhang San (Company) email zhangsancompany.com~/.gitconfig-personal内容[user] name Zhang San email zhangsanpersonal.com这样只要仓库位于~/work/目录下Git就会自动使用公司身份位于~/personal/目录下就自动使用个人身份。不需要手动配置local也不会因为忘记设置而提交错身份。关于这个方案还有两个经验。第一gitdir:的路径建议用绝对路径避免被当前工作目录干扰。第二includeIf的配置属于global层级的条件分支如果仓库内还有local配置local仍然是最终赢家。这意味着你可以在个别仓库里做临时覆盖灵活性很高。4. 配置不生效、提交作者错乱问题排查与避坑实录4.1 明明配置了user.name提交作者还是unknown怎么办最常见的排查步骤是这样的先看配置是否真的写进去了。git config --list --show-origin git var GIT_AUTHOR_IDENT如果git var输出里的邮箱是空的或者显示成unknown说明配置没有生效。原因通常有这几个第一配置写错了层级。比如你用了--system却因为权限不足没写成功或者仓库里有local配置覆盖了global。用--show-origin看来源一目了然。第二环境变量覆盖了配置文件。Git支持GIT_AUTHOR_NAME、GIT_AUTHOR_EMAIL、GIT_COMMITTER_NAME、GIT_COMMITTER_EMAIL这一组环境变量它们的优先级比配置文件高。如果你在~/.bashrc或者CI脚本里设过这些变量就会覆盖掉配置文件里的值。检查一下环境变量env | grep GIT_第三GUI工具自带身份配置。Sourcetree、TortoiseGit这类客户端在创建仓库或提交时有自己独立的身份填写入口。如果你在Git命令行配了身份但用GUI提交时还是不对那多半是GUI里另外写了一套配置。以TortoiseGit为例需要进入“Settings - Git”在全局或仓库级别设置用户名和邮箱。对这个工具来说它读取的仍然是Git配置但因为界面入口比较隐蔽很多人只改命令行配置忽略了GUI自己的设置。补充一个实用命令如果你发现某次提交已经用了错误身份可以用以下命令查看全部提交的作者邮箱分布git log --format%ae | sort | uniq -c这样能快速看出历史提交里混入了多少个不同的邮箱便于定位问题范围。4.2 邮箱填错了贡献图不显示、绿格子不亮怎么办不少人在GitHub或Gitee上提交了一堆代码结果个人主页的贡献图一片空白。最常见的原因就是提交时用的邮箱和平台账号绑定的邮箱不一致。这里说明一下平台的匹配机制平台会把提交记录里的邮箱和账号已绑定的邮箱做匹配。匹配成功这条提交才会关联到你的账号下并点亮贡献图匹配失败提交记录虽然还在仓库里但不会显示在你的个人主页上。解决办法有两个方向。第一个方向修改平台设置把历史用过的邮箱全部添加到账号里。比如在GitHub的“Emails”设置页面可以添加多个邮箱作为备用邮箱。这样即使历史提交里的邮箱是旧邮箱也能正确关联到账号。第二个方向修改历史提交的作者邮箱把旧邮箱批量改成新邮箱。这个操作会重写提交哈希比较暴力。如果你只是改最近一次提交可以用git commit --amend --reset-author执行后Git会让你重新输入作者信息然后把最新的提交替换掉原来的。如果你需要批量修改历史提交可以用git filter-branch。比如把旧邮箱oldexample.com统一替换成newexample.comgit filter-branch --env-filter if [ $GIT_AUTHOR_EMAIL oldexample.com ]; then GIT_AUTHOR_NAMEZhang San GIT_AUTHOR_EMAILnewexample.com GIT_COMMITTER_NAMEZhang San GIT_COMMITTER_EMAILnewexample.com fi -- --all注意filter-branch会改变所有受影响提交的哈希值。如果这些提交已经推送到远端并且有其他协作者基于它们工作那么强推之后会让所有人的本地仓库陷入混乱。所以只要提交已经推送出去了又涉及到协作分支我都不建议用重写历史的方式去改作者信息。更稳妥的做法是从当前时间点开始保证邮箱正确同时把旧邮箱添加到平台账号的备用邮箱列表里。另外提一个隐私相关的配置如果你不想在公开仓库里暴露真实邮箱GitHub提供noreply邮箱功能Gitee和GitLab也有类似机制。具体格式可以在平台的“Emails”设置页面找到。把这个noreply邮箱填入user.email既能正常关联账号又能避免真实邮箱被爬虫抓取。4.3 邮箱端口、授权码、Token这些概念被混在一起了结合很多搜索热词来看不少人把Git配置邮箱和邮箱客户端配置搞混了。搜“邮箱端口”“微软邮箱授权码”的人可能以为Git配置邮箱也需要填收件服务器、发件服务器、端口、授权码之类的东西。这里再次明确Git配置邮箱真的只需要填一个邮箱地址字符串。不涉及端口不涉及授权码不涉及密码。user.email的唯一作用就是作为字符串写进提交元数据里。真正需要密码或Token的场景是推送代码时和代码托管平台的认证。以GitHub为例从2021年8月起HTTPS方式推送不再支持账号密码只支持Personal Access Token。在Gitee上HTTPS推送也会要求使用账号密码或Token。这个认证信息通常由Git的凭据管理器负责保存和.gitconfig里的身份配置是两个独立的流程。所以如果你碰到“Git提示认证失败”处理方向是去平台生成Token或者在SSH密钥设置上找问题而不是去改邮箱配置。4.4 修改历史提交中的作者信息这一节专门给那些意识到“历史提交邮箱错了必须修正”的人。除了前面提到的filter-branch还有更现代的替代工具git filter-repo。它比filter-branch快很多也更安全但需要单独安装。想修正某个旧邮箱对应的所有提交核心思路是一样的通过环境变量覆盖GIT_AUTHOR_*和GIT_COMMITTER_*。只是filter-repo的语法更干净一些。git filter-repo --mailmap或者用--email-callback但这里不展开太多。我的建议是如果不是特别必要不要重写历史。因为绝大多数场景下“把旧邮箱加入平台备用邮箱”就能解决贡献图关联问题完全不需要动历史提交。只有在团队成员明确要求清洗历史或者仓库还处于早期开发阶段、没有大量协作者时才考虑重写。重写之后所有克隆过这个仓库的人都需要重新拉取或强推协作成本很高。4.5 配置文件的备份与迁移新换电脑时最痛苦的莫过于重新配置一遍Git环境。这里分享一个实用习惯把~/.gitconfig纳入dotfiles管理换机器时直接复制或者通过配置管理工具一键部署。但有一点要特别注意不要把敏感信息写进.gitconfig。有些人在~/.gitconfig里保存过http.extraHeader或者自定义的credential.helper参数这些内容可能包含Token、私有地址等敏感信息。如果这份配置文件要分享到仓库或博客里一定要提前检查一遍。安全的分享内容通常包括user.name、user.email不介意公开的话、别名、颜色配置、includeIf、core.quotepath等非敏感设置。5. 团队协作中的身份规范建议5.1 公司内网环境下的邮箱怎么填如果你在公司环境使用Git提交邮箱应该优先使用公司统一的身份邮箱。不少企业内部代码平台会根据提交邮箱关联到企业账号甚至要求邮箱与目录服务账号一致否则代码评审系统无法正确识别提交人可能导致评审通知发不到正确的人手里。具体邮箱格式以团队规范为准。有的是工号company.com有的是姓名拼音company.com。新入职的时候可以问一下同事或查一下团队wiki不要凭感觉填一个个人邮箱。填错了轻则贡献图不亮重则代码归属出问题后面纠正起来非常麻烦。5.2 给新人的一份“提交前检查清单”最后整理一份检查清单新机器也好旧机器也好配置完Git之后花一分钟过一遍已设置git config --global user.name值是自己常用的展示名。已设置git config --global user.email值是可以关联到代码平台账号的邮箱。执行git config --list --show-origin确认没有意外来源的配置。如果这台电脑要同时用于公司和个人的代码仓库确认是否已经用local或includeIf做好身份隔离。首次提交后执行git log -1 --format%an %ae确认作者信息正确。如果用的是GUI客户端额外确认客户端里的身份设置和命令行配置一致。这几点看着基础但每次换电脑、换工作、接手新仓库时过一遍能省下后面大量排查时间。我个人在实际操作中的体会是Git的身份配置属于那种“十分钟搞定搞不定折腾三天”的典型问题。因为如果一开始没配好后续积累了大量错误提交再想纠正就牵一发动全身。所以我的习惯是新机器到手、装完Git第一件事先把git config --global user.name和user.email写好再考虑clone代码。最后分享一个小技巧如果你担心哪天漏配身份导致提交挂到unknown头上可以在~/.gitconfig里加一个强制校验开关[user] useConfigOnly true这个配置开启后Git在提交时会强制要求当前仓库存在明确的user.name和user.email否则直接拒绝提交。这样就不会因为global缺失或环境变量被污染而悄悄产生错误作者记录了。对于团队新人的电脑这个配置尤其有用。