1. 这个报错到底在烦什么passphrase 和 password 不是一回事先聊个最基本的认知问题。很多人在 Mac 上配好 Git 之后第一次执行git push或git pull终端突然弹出一句Enter passphrase for key /Users/你的用户名/.ssh/id_ed25519:这时候好多人第一反应是我 Git 密码不是这个啊我 GitHub 密码也试了都不对怎么回事这里的关键在于passphrase口令短语和你平时登录 GitHub 网页用的password登录密码完全是两个东西。passphrase是你本地 SSH 私钥文件的解锁密码。简单说当你用ssh-keygen生成密钥对时如果你顺手输入了一串字符作为保护口令那这串字符就是 passphrase。它在本地加密你的私钥每次要用私钥做认证时系统都会要求你输入这串口令来解开私钥。更直白的理解方式password 是门禁卡passphrase 是保险柜密码锁的钥匙。你把 SSH 公钥放到 GitHub 服务器上相当于在服务器门口贴了你的身份证明但你的身份证明原件私钥放在本地保险柜里保险柜的锁就是 passphrase 锁的。每次服务器要核验你身份时Git 先得打开本地保险柜拿私钥出来所以它问你的是保险柜密码不是门禁卡密码。那原来的需求就很明确了我不想每次 push/pull 都输一遍这个 passphrase能不能让 Git 自动记住、自动解锁、或者干脆把私钥的 passphrase 去掉。网上搜git ignore passphrase的人多半是卡在了每次都要输入这个体验上。下面我会把几种可行的方案都拆开讲包括各自的适用场景和副作用。2. 先搞清楚你用的是哪种认证方式再决定怎么处理看到 passphrase 提示先别急着改配置。花三十秒确认一下你的 Git 是走 HTTPS 还是 SSH因为这两条路的免密方案完全不一样。2.1 查看当前仓库的远程地址类型在项目目录下执行git remote -v输出结果有两种典型形态# SSH 方式 origin gitgithub.com:用户名/仓库名.git (fetch) origin gitgithub.com:用户名/仓库名.git (push) # HTTPS 方式 origin https://github.com/用户名/仓库名.git (fetch) origin https://github.com/用户名/仓库名.git (push)如果是gitgithub.com开头说明走的是 SSH如果是https://github.com开头说明走的是 HTTPS。passphrase 提示只会在 SSH 方式下出现因为 HTTPS 方式根本不会用到 SSH 密钥。2.2 macOS 钥匙串在 HTTPS 场景下的作用走 HTTPS 的时候你需要的是让 Git 记住账号密码这时候 macOS 的钥匙串Keychain就有用了。如果你之前配过全局用户名和邮箱大概率会遇到密码提示本质是访问令牌Personal Access Token或账号密码没被缓存。处理方式是用系统自带的凭据管理器git config --global credential.helper osxkeychain这个配置的意思是让 Git 在需要凭据时通过 macOS 的钥匙串来存取。第一次输入后凭据会被写入钥匙串之后就不再询问。这是 HTTPS 场景下免密的标准做法和 passphrase 没关系但经常被人混在一起问。2.3 SSH 场景才需要处理 passphraseSSH 方式下远程地址里的gitgithub.com会让你本地的~/.ssh/目录发挥作用。Git 会在那个目录下找私钥文件比如id_ed25519或id_rsa。如果你的私钥有口令保护Git 就会问你要 passphrase。判断依据很直接私钥文件本身是否被加密过。用下面命令看head -n 1 ~/.ssh/id_ed25519如果文件开头是-----BEGIN OPENSSH PRIVATE KEY-----这只能说明它是 OpenSSH 格式的私钥看不出有没有加密。想确认是否加密用 ssh-keygen 的检查命令ssh-keygen -y -P -f ~/.ssh/id_ed25519 /dev/null 21 echo 无口令 || echo 有口令或路径错误上面这个命令用空密码尝试读取私钥如果成功说明没设 passphrase如果失败说明私钥本身有口令保护。这一步是后面所有操作的前提先确认状态再动手。3. 方案一让 macOS 钥匙串替你保管 passphrase这是我最推荐日常使用的方案。它并不移除私钥的 passphrase而是让系统在你第一次输入后帮你记住后续自动解锁。好处是安全性还在只是手动输入这个动作被省掉了。3.1 核心操作配置 ~/.ssh/config在终端执行nano ~/.ssh/config如果文件不存在nano 会新建。写入以下内容Host * UseKeychain yes AddKeysToAgent yes IdentityFile ~/.ssh/id_ed25519逐行解释一下Host *匹配所有 SSH 连接目标不限于 GitHub如果你有 GitLab、公司内网 Git 服务器也一并生效。UseKeychain yesmacOS 特有的选项表示将 passphrase 存入系统钥匙串。AddKeysToAgent yes解锁后的密钥自动添加到 ssh-agent后续在同一会话内不再询问。IdentityFile指定使用哪个私钥文件。如果一开始生成密钥的时候用的不是默认文件名这里要改成实际路径。保存退出后再执行一次git pull或git push这时会提示你输入一次 passphrase。输入正确后macOS 会弹窗询问是否允许 ssh-agent 访问钥匙串选始终允许即可。之后就不会再问了。3.2 为什么要用 ssh-agent 做中转这里补充一个底层逻辑。很多人搞不懂UseKeychain和AddKeysToAgent搭配起来发生了什么当 Git 发起 SSH 连接时SSH 客户端先去找 ssh-agent 要密钥。agent 手里没有时才会去读私钥文件发现文件有口令保护于是向终端要 passphrase。UseKeychain yes让系统在第一次输入后把口令存进钥匙串下次 SSH 客户端要口令时直接从钥匙串里取不再显示命令行交互。AddKeysToAgent yes的作用是把已经解锁的私钥缓存到 agent 进程里。agent 的缓存是常驻内存的一个终端会话里多次操作都不需要反复取钥匙串。双重保障体验上就是回车直接通过。你可能会问为什么不直接去掉 passphrase如果只是个人开发电脑去掉其实也行但我不建议。因为一旦笔记本丢失私钥文件等于裸奔任何人拿到文件就能冒充你连接远程仓库。保留 passphrase、但用钥匙串托管是在安全和便利之间比较好的平衡点。3.3 实测中要注意的两件事第一UseKeychain yes是 macOS 专属配置。如果哪天你把同一个~/.ssh/config复制到 Linux 或 Windows 上用SSH 客户端会直接报错Bad configuration option。所以跨平台共用一份配置时这个选项要单独处理。第二macOS 升级后有时会出现明明配置了 UseKeychain却依然频繁询问 passphrase的情况。大概率是钥匙串权限变更导致 ssh-agent 无法读取。解决办法是打开钥匙串访问App找到ssh-agent或com.apple.ssh-agent条目确认访问控制里允许ssh-agent访问如果还不行删掉相关条目重新授权再执行一次 push 重新录入即可。4. 方案二彻底移除私钥的 passphrase如果你的场景是持续集成、脚本自动部署或者你觉得这电脑只有我自己用没必要加密私钥那可以直接把私钥的口令去掉。这个操作一劳永逸彻底消灭 passphrase 提示。4.1 操作命令与备份建议执行cp ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.bak ssh-keygen -p -f ~/.ssh/id_ed25519ssh-keygen -p的意思是 change passphrase修改口令短语。执行后它会先问Old passphrase输入你当前的口令然后连续两次让你输入New passphrase这时候直接按回车也就是留空就表示新口令为空。备份那一步千万别省。万一操作中按错键、输错口令导致私钥文件损坏你还能从.bak文件恢复不至于重新生成密钥再配置 GitHub。生成密钥简单但你要重新把公钥配到 GitHub、GitLab、公司服务器等一堆地方那才是真麻烦。所以备份文件留着确认一切正常后再删。确认修改成功ssh-keygen -y -P -f ~/.ssh/id_ed25519这条命令用空口令读取私钥如果能正常打印出公钥内容说明 passphrase 已被移除。注意输出内容是公钥不要随意公开。4.2 移除后的安全边界去掉 passphrase 意味着私钥本体不再加密。一旦文件泄露拿到的人直接能用它做认证。因此强烈建议在移除口令的同时做好两件事一是限制私钥文件权限。检查一下ls -l ~/.ssh/id_ed25519正常的权限应该是-rw-------即仅当前用户可读写。如果显示的是-rw-r--r--或更宽松的权限立刻收紧chmod 600 ~/.ssh/id_ed25519同时把~/.ssh目录权限改为 700chmod 700 ~/.ssh二是如果你在公司多人共用电脑或者电脑有被远程访问的可能建议不要用这个方案。去掉口令这个操作本质上是把保险柜门拆了。个人开发机、物理隔离环境可以这么干共享环境还是用方案一或者方案三。4.3 什么情况下选这个方案我自己在实际项目中见过几种人适合方案二跑 CI/CD 的构建机构建过程需要频繁拉代码没法每次都有人工输入。当然构建机通常有自己的部署密钥但如果是临时搭建的机器直接用无口令密钥最省事。个人主力开发机且已启用硬盘加密FileVault。系统登录后有全盘加密保护私钥文件即便明文存放也在系统盘加密层之下风险可控。一些旧版自动化脚本调git pull时无法交互式输入口令。这类脚本环境下去掉 passphrase 是快速见效的办法。5. 方案三只在当前 shell 会话内记住不写入任何配置文件有些时候你既不想动钥匙串、也不想改私钥本身只想这次开机后、这个终端窗口里免输入。这种情况用 ssh-agent 手动加载即可。5.1 手动添加私钥到 agent 会话eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519执行ssh-add时系统会要求你输入一次 passphrase。输入正确后私钥被加载进当前 ssh-agent 进程。之后这个终端会话里所有 Git 操作都不会再问 passphrase。如果你用的是 zsh可能遇到过eval $(ssh-agent -s)每次打开新终端都要执行一次的麻烦。一个比较实用的做法是将其写入~/.zshrc但我不太推荐无脑加因为每个终端窗口都自动启动一个 agent进程多了反而乱。更稳妥的写法是让 shell 只在检测到 agent 未运行时才启动它。bash if [ -z $SSH_AUTH_SOCK ]; then eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 fi这段的意思是如果当前环境变量里没有 SSH_AUTH_SOCK说明没有可用的 agent 会话就启动一个并加载密钥。如果你之前已经手动了 ssh-add再开新窗口时它会要求重新输 passphrase 吗会。这就是方案三和方案一的最大区别钥匙串能在系统层面持久保存口令agent 只是内存缓存重启电脑后缓存就没了。 ### 5.2 与方案一的组合使用 其实方案三和方案一并不冲突。很多人会同时配置 UseKeychain yes 和 AddKeysToAgent yes然后仍然偶尔手动执行 ssh-add目的就是让当前会话立即解锁不等第一次 push 时再触发提示。本质上是在系统持久记忆和当前进程缓存两层都做好准备体验最顺滑。 ### 5.3 排查 ssh-add 失败的情况 ssh-add 偶尔会报 Could not open a connection to your authentication agent。字面意思是没有 agent 进程可连接。解决办法就是先跑一下 eval $(ssh-agent -s)。但注意如果你在 tmux 或 screen 里开多窗口这个命令的输出要能被所有窗口共享最简单的方式是在启动 tmux 之前先启动 agent 并加载密钥然后整个 tmux 会话里继承环境变量。 这个坑我踩过好几次。进了 tmux 再执行 ssh-add大概率撞上 agent 连不上解决方式是 start tmux 前先 ssh-add或者用 ssh-agent 包装 tmux 启动命令让所有子窗口共享同一个 agent socket。 ## 6. 方案四换用 Deploy Key 或只读 Token适合非交互场景 前面三个方案处理的都是本地如何自动解锁私钥。但还有一种角度既然 passphrase 是在私钥层面出现的那我可以不用私钥。GitHub 提供了 Deploy Key 和 Personal Access Token 两种替代形态。 ### 6.1 Deploy Key 解决的是单仓库免密拉取 Deploy Key 的本质是给某个仓库单独配一对 SSH 密钥公钥放到当前仓库的 Deploy Keys 里私钥留在服务器或本机而不是绑在你的个人账号上。它的好处是权限范围小只读或读写该仓库即使密钥泄露也不会影响你的其他仓库。 操作路径GitHub 仓库页面 - Settings - Deploy keys - Add deploy key。把公钥内容贴进去勾选 Allow write access 如果需要写权限。然后在本地写好 ~/.ssh/config比如 bash Host github-deploy HostName github.com User git IdentityFile ~/.ssh/deploy_key_xxx IdentitiesOnly yes再把仓库远程地址改成git remote set-url origin gitgithub-deploy:用户名/仓库名.git这样 push 和 pull 都走 deploy key 的私钥和账号私钥完全隔离。如果 Deploy Key 对应的私钥也没设 passphrase那就彻底不需要任何口令交互了。6.2 Personal Access Token 适用于 HTTPS 备份如果你确定要走 HTTPS又不想用 macOS 钥匙串可以给 GitHub 账号生成一个 Personal Access TokenPAT用它的用户名密码片段填入 git 凭据。注意 PAT 本质上是带权限的令牌和你的账号密码是两码事。生成路径GitHub 头像 - Settings - Developer settings - Personal access tokens - Tokens (classic) - Generate new token。按需勾选repo、workflow等权限。生成后只显示一次要立刻复制保存。使用方式把远程地址改成git remote set-url origin https://用户名:PATgithub.com/用户名/仓库名.git这样写虽然能用但令牌字符串会直接暴露在.git/config里不太推荐长期这么干。更稳妥的方式还是配合credential.helper osxkeychain让钥匙串替你记令牌URL 里不带敏感信息。6.3 三种方案怎么选场景推荐方案理由日常个人开发想省去重复输入方案一钥匙串托管安全性和便利性平衡保留了私钥加密层定制的脚本、容器、CI 机器方案二移除 passphrase或 Deploy Key无需人工交互权限可控单次会话内快速操作方案三ssh-agent 手动加载不写持久配置重启即失效独立仓库、需要最小权限方案六Deploy Key密钥只对该仓库生效隔离风险HTTPS 场景想免密钥匙串 PAT用系统钥匙串托管令牌7. 真正的坑配置了依然被反复要求 passphrase上面每个方案都介绍完了但实战中大概率会遇到配置了还是被问的情况。下面把最常见的原因整理成一张排查表按顺序检查能省很多时间。现象可能原因解决办法配了 UseKeychain 但还是被问钥匙串权限异常钥匙串访问 - 查找 ssh-agent 条目 - 允许访问git pull 被问但 ssh -T gitgithub.com 正常仓库远程地址写了 IP 或别名没有走 config 的 Host 匹配git remote -v核对地址确保 Host 匹配私钥路径不对配置里的 IdentityFile 与默认文件名不同ssh -i ~/.ssh/xxx gitgithub.com手动测试使用多个私钥GitHub 拒绝了默认 key 被优先使用且不含目标地址的授权config 中加IdentitiesOnly yes配置改了没生效ssh-agent 缓存旧状态ssh-add -D清空代理缓存重新加载SSH agent 工作异常环境变量丢了echo $SSH_AUTH_SOCK检查无输出则执行eval $(ssh-agent -s)macOS 升级后行为变化钥匙串 ACL 被重置到钥匙串应用重新授权 ssh-agent7.1 最隐蔽的一个坑Host 匹配范围过宽很多人把~/.ssh/config写成Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 UseKeychain yes AddKeysToAgent yes看起来没什么问题。但如果你仓库的远程地址写的是gitgithub.com:xxx/yyy.git它确实会命中。可如果你用的是公司内网 GitLab地址是gitgitlab.company.com:group/project.git上面的配置就完全不管用。H 匹配不上SSH 客户端会回退到默认行为不加载钥匙串于是 passphrase 又冒出来。解决办法是加一个通配 HostHost * UseKeychain yes AddKeysToAgent yes或者为不同 Git 服务分别写 Host 段落避免优先级混乱。另一个相关项是IdentitiesOnly yes当你有多个私钥时SSH 会逐个尝试如果你注释掉了这个选项bash IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes加上 IdentitiesOnly yes 告诉 SSH 客户端不要乱试其他密钥只使用配置里指定的一个。这样能减少试了多个密钥都不对带来的额外提示。 ### 7.2 排查链路参考 我自己遇到配置一切正常但还问 passphrase时排查顺序是固定的 bash # 第一步确认远程地址 git remote -v # 第二步模拟 SSH 连接确认认证本身没问题 ssh -T gitgithub.com # 第三步用详细模式打印 SSH 握手过程看它实际用了哪个私钥 ssh -vT gitgithub.com 21 | grep Offering public key第三步最关键。它会告诉你 SSH 客户端到底尝试了哪些密钥。如果输出的密钥文件名不是你配置的那个那问题就出在 config 的匹配或IdentitiesOnly缺失上。注意ssh -vT的输出对新手来说非常长先 grep 关键词能快速定位。7.3 为什么改了 config 有时候不生效SSH config 的生效机制是每次建立新连接时读取一次。如果你在一个开了很久的终端里测试shell 里的历史 SSH 连接状态会被 agent 缓存表面上像没生效。稳妥起见改配置后先执行ssh-add -D清空 agent 里的全部密钥缓存再重新测试。这样能排除缓存干扰准确验证新配置是否生效。注意-D会清掉所有代理内的密钥之后如果还需要用得重新ssh-add。8. 从忽略 passphrase看 Git 凭据管理的整体思路聊到这儿你会发现MAC 上忽略 passphrase并不是一个孤立的小问题。它背后其实是 Git 本地凭据管理的整体逻辑私钥要不要加密、加密口令存哪里、何时自动解锁、用哪种连接协议。我的建议是先想清楚自己的使用场景再选方案如果你是个人开发者电脑只有你一个人用FileVault 也开着推荐方案一钥匙串托管既有加密又免输入。如果你在配置自动部署脚本、跑 CI需要无人值守地拉代码推荐 Deploy Key 或无 passphrase 的专用密钥按仓库最小授权来设计。如果你只是临时在某个环境里需要快速同步一次代码方案三的 ssh-agent 手动加载最轻量。另外提醒一点passphrase 和你团队协作时同事问的Git 密码无关。如果同事一直说我输对了密码但 push 不了大概率是认证方式混淆或者 SSH key 没配好。你可以用上面ssh -T gitgithub.com来快速验证网络层的认证是否正常再判断问题在哪一层。最后再分享一个我自己实际用过的小技巧如果在公司电脑上既要连 GitHub 个人仓库又要连公司 GitLab建议给两个场景各配一把独立密钥并在~/.ssh/config里用两个 Host 块分离开分别指定IdentityFile和UseKeychain。这样互不干扰也不会出现公司机器上 push 个人仓库一直要输 passphrase的割裂感。配置结构大致是# 个人 GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes UseKeychain yes AddKeysToAgent yes # 公司 GitLab Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company IdentitiesOnly yes UseKeychain yes AddKeysToAgent yes这样配好后无论在哪台机器上SSH 都会按远程地址自动选择对应密钥和钥匙串策略基本不会再被 passphrase 打扰。