很多人第一次接触 Sourcetree是在网上搜“Sourcetree 安装教程”想解决 Git 操作太抽象的问题。确实和 Git Bash 那一堆命令相比Sourcetree 这种图形化工具给人的第一印象友好得多分支、提交、推送、拉取都是按钮和线条鼠标点一点就完事。可不少人真正动手装上之后反而卡在了一些莫名其妙的地方——账号登录页绕不过去、Git 不知道装没装、SSH 密钥死活配不上、打开就弹“用户设置必须被修复”。这多半不是 Sourcetree 本身难装而是安装前没搞清楚几个关键点安装时又错过了一些选项。这篇文章我就从实操角度把 Sourcetree 从下载到首次配置的完整过程拆开讲一遍。 主要覆盖 Windows 和 macOS 两套系统的安装差异、首次启动时用户设置的处理、SSH 密钥包括 ED25519的配置以及装完之后最常遇到的报错怎么查。适合刚接触 Git 图形化工具的小白也适合装到一半卡住、准备重装的人。1. 安装前先解决三个疑惑Git、Sourcetree、账号到底什么关系1.1 Sourcetree 不是 Git它只是 Git 的图形化操作界面很多人以为装完 Sourcetree 就等于装好了 Git这个理解不太对。Sourcetree 本质上是一个 Git 客户端负责把 Git 的命令行操作翻译成图形界面。真正执行版本管理工作的还是底层那个 Git 引擎。打个比方Git 像是汽车的发动机Sourcetree 像是方向盘和仪表盘。你开车不需要天天掀开发动机盖但发动机必须存在。Sourcetree 在 Windows 下的安装包确实会顺手带一个嵌入式 Git但如果你之前已经装过独立的 Git最好在安装时让 Sourcetree 去调用系统 Git而不是内置那个嵌入式版本。原因后面会讲。在 macOS 上情况不太一样macOS 系统本身可以借助 Xcode Command Line Tools 提供 GitSourcetree for Mac 在首次启动时也会提示安装这些命令行工具。这个细节直接决定了后续能不能正常推送代码。1.2 为什么要用图形客户端不直接用命令行如果你之前只听说过 Git还没上手敲过命令我的建议是第一遍用 Sourcetree 没问题它能帮你建立分支、提交、合并这些操作的直觉。比如“分支”这个概念在命令行里你只能看到一串 hash 和指针而在 Sourcetree 里你能看到一条条分支线分叉又汇合理解成本低很多。但我也得说实话Sourcetree 不是万能的。遇到冲突文件特别多、需要交互式 rebase、或者想在命令行里跑自动化脚本的时候最终还是得回到 Git 命令。所以不要在 Sourcetree 里待得太舒服用它作为入门的跳板没问题但别把命令行彻底丢一边。实际项目里很多协同问题恰恰是在图形界面看不到细节时才暴露出来的。1.3 账号登录页到底该不该跳过Sourcetree 是 Atlassian 家就是做 Jira、Confluence 那家的产品所以首次启动会有一个 Atlassian 账号登录页面。在国内网络环境下这一步经常卡很久甚至登录超时。这里有一个非常实用的技巧这个 Atlassian 账号不是必须要登录的。 界面上有一个“Skip this step”或者“稍后跳过”的选项直接跳过完全不影响本地使用你照样可以克隆仓库、提交代码、切换分支。只有当你需要连接 Bitbucket或者想用 Sourcetree 内置的一些 Atlassian 云服务功能时才需要登录账号。所以安装教程看到登录页千万别慌能跳就跳。2. 下载之前的环境自查和版本选择2.1 系统环境Windows 和 macOS 的基本要求Sourcetree 没有 Linux 版本这一点要先说清楚。Windows 版目前支持 Windows 10、Windows 11以及仍在维护期的 Windows Server 版本。太老的 Windows 7 虽然某些老版本能跑但新版本基本不再支持装上了也容易出现依赖库缺失的报错。macOS 版要求相对宽松一些但也要注意芯片架构。Apple SiliconM1/M2/M3 系列和 Intel 芯片的 Mac 现在官方安装包通常都是通用包Universal安装基本没区别。不过如果你在 Mac 上用的是老版本 macOS建议先去官网看下当前版本对应的最低系统要求。另外一个容易忽略的点在 Windows 上Sourcetree 安装时会检测系统中是否已经有 Git。如果你安装过 GitHub Desktop、Visual Studio 或者 Xcode 这类自带 Git 的工具系统 PATH 里可能已经有 Git 了。这时候 Sourcetree 的安装向导会询问是用“嵌入式 Git”还是“系统 Git”很多人不看直接下一步结果之后克隆仓库时报出各种诡异错误。2.2 官网下载还是第三方下载站下载 Sourcetree 我强烈建议去官网sourcetreeapp.com不要贪方便从第三方下载站下。原因有几个一是第三方站的版本经常滞后可能是好几年前的旧版界面和使用逻辑差了一大截二是安装包这种东西被捆绑插件或改过的风险实在不值得冒。官网下载页会根据你的操作系统自动给出对应版本Windows 是 exe 安装器macOS 是 dmg 镜像。如果你在国内网络环境下官网下载速度慢可以尝试用下载工具或浏览器自带的多线程下载但别为了速度去下载“破解版”“绿色版”。Sourcetree 本身对个人用户是免费的不存在破解需求。2.3 安装前到底要不要先单独装 Git这问题被问烂了但确实值得再讲一次因为“sourcetree 如何下载 git”这种搜索词一直居高不下。结论分两种情况Windows建议先自己装一个 Git for Windows再用 Sourcetree 的安装向导指向系统 Git。Sourcetree 内置的嵌入式 Git 也能用但功能版本更新慢遇到大型仓库或新协议支持时容易吃亏。手动装 Git 时不建议随意改安装选项默认配置即可安装过程中勾选“将 Git 加入 PATH”即可。macOS如果你已经通过 Xcode 或 Homebrew 装过 GitSourcetree 会自己找到如果没装首次启动时它会引导你安装 Command Line Tools。这一步允许安装后面就不会因为找不到 Git 而报错。一句话总结先有 Git再装 Sourcetree体验最省心。3. Windows 下完整安装步骤与关键选项详解3.1 双击安装包之后注意看这里的每一步下载完成之后双击那个 exe 文件Sourcetree 的安装向导就会开始。第一个界面除了许可协议就是“Install”按钮点进去之后它会先检查系统里有没有 Git。如果它检测不到系统 Git安装界面会出现一个选项问你是否安装内置的嵌入式 Git或者要你自己指定 Git 的路径。这里我建议优先选“Use system Git”然后在路径栏里填上你装的 Git 的可执行文件路径一般形如C:\Program Files\Git\bin\git.exe。如果不确定路径可以在命令行里敲where git查看。这一步选错确实会影响后面使用选嵌入式 Git 的话Sourcetree 不会自动补充到你系统的环境变量里其他终端工具调用不到选系统 Git 则能保证 Sourcetree 和命令行操作的是同一个 Git 底层代码历史、忽略规则这些行为完全一致不会出现两边结果不一致的割裂感。3.2 安装选项里容易被忽略的两个小点Windows 安装器有一步会问是否创建开始菜单快捷方式、是否添加桌面图标这些无所谓按喜好来。真正值得注意的是安装完成后首次运行的默认设置语言选择Sourcetree 较新版本默认跟随系统语言如果你的 Windows 是中文界面会显示中文不汉化也完全能看懂因为按钮和菜单就那几项。默认根目录它可能问你想把仓库默认放在哪个目录。这里没必要改后续克隆仓库时可以单独选择路径。这个阶段唯一要记住的是别看到 Atlassian 账号登录入口就以为必须输账号直接跳过。3.3 安装完成后的一小时验证环境与高频报错排查Sourcetree 装好但用不了多半不是没装成功而是首次启动配置没做好。这里我列一个排查顺序按这个顺序走基本能把问题解决确认 Git 可用。在 Windows 的 cmd 或 PowerShell 里输入git --version能看到版本号说明 Git 正常。打开 Sourcetree它应该会告诉我们当前使用的 Git 版本路径来自系统 Git 或嵌入式 Git。如果这里显示“无法识别 Git”回到安装选项里把路径重新指一下。如果启动时就弹“用户设置必须被修复”别急着重装这是 Sourcetree 检测到当前电脑上的全局 Git 配置有问题。后面第 5 章我会专门处理。另一个常见问题是 Win11 用户安装完成后点击图标没反应。这多半是安装过程被 Windows SmartScreen 拦了。右键安装包选择“属性”在“常规”页里如果能看到“解除锁定”按钮点一下再重新安装就能避免这种无响应。3.4 关于“Sourcetree 用户设置必须被修复”到底该怎么处理这个报错在中文搜索里出现频率很高也是很多人重装 Sourcetree 的罪魁祸首。它出现的原因是 Sourcetree 在启动时要读取全局 Git 配置包括 user.name 和 user.email如果读不到、读取异常或者全局配置里存在一些它无法解析的内容就会弹“Your user settings must be fixed”之类的提示。处理方式很简单Sourcetree 会给你一个“修复”按钮。点击修复后它会在弹出的配置页里要求你填写用户名和邮箱这两项会被写入 Git 的全局配置。修复完重新启动一般就好了。如果点击修复没反应可以手动在命令行里执行git config --global user.name 你的名字 git config --global user.email 你的邮箱执行完再打开 Sourcetree它就不会再报这个错了。有些人会问为什么一定要填邮箱因为这个邮箱会被写进每一次提交的 commit 信息里是展示给其他协作者看的身份标识。如果填的是角色账号或者别人的邮箱后续排查提交记录时会很麻烦。4. macOS 用户会遇到的安装差异和 Gatekeeper 处理4.1 dmg 安装包里其实是个拖拽安装macOS 版 Sourcetree 的安装方式和 Windows 差很多下载下来是一个 dmg 文件双击挂载之后打开一个带 Sourcetree 图标的窗口你需要把图标拖到旁边的 Applications 文件夹里。这个拖拽过程就是安装本身没有任何下一步下一步的向导。拖拽完再从“启动台”或“应用程序”里打开 Sourcetree。第一次打开时macOS 的 Gatekeeper 会拦一道提示“无法验证开发者”或“来自互联网的下载”。这不是病毒而是因为 Sourcetree 并没有在 Mac App Store 里上架。处理办法打开“系统设置”里的“隐私与安全性”在底部看到“仍要打开”之类的选项点击确认就能正常启动。如果连这个选项都没有再考虑右键图标选择“打开”来绕过一次性拦截。4.2 首次启动会要求安装 Command Line Tools在 Mac 上启动 Sourcetree 时它会检查系统是否有 Git。如果你的 Mac 从来没装过 Xcode 或 Homebrew那么系统里很可能是没有 Git 的。此时 Sourcetree 会弹出一个对话框建议你安装 Apple 的 Command Line Tools。这个安装包大概几百 MB下载速度取决于网络环境但必须装。装完 Command Line ToolsGit 就有了Sourcetree 也能正常识别。有些同学之前用 Homebrew 装过 Git那么 Sourcetree 会直接用 Homebrew 的 Git 路径不用再装 Command Line Tools。区分方式是看 Sourcetree 首选项里的 Git 版本路径如果是/usr/bin/git就是系统自带的如果是/usr/local/bin/git或/opt/homebrew/bin/git就是 Homebrew 装的两个都好使。4.3 Mac 版没有“嵌入式 Git”的概念和 Windows 版不同macOS 版 Sourcetree 不提供嵌入式 Git 选项它只会去找系统里已经存在的 Git。这意味着你如果之前没装 Git就必须走上面那一步装 Command Line Tools。理解了这一点就不会在 Mac 上到处搜“为什么我的 Sourcetree 没有选择 Git 的步骤”了。另外有个小细节Mac 的 Sourcetree 在首次配置时也会问 Atlassian 账号和外观偏好同样可以直接跳过。5. 首次启动配置用户设置、账号跳过和 SSH 密钥生成5.1 做完修复之后再检查一次全局用户配置不论 Windows 还是 Mac第一次打开 Sourcetree 时界面大概率会停在用户设置页要求填用户名和邮箱。这里我特别建议填完再验证一下git config --global --list如果能看到user.name和user.email说明全局配置已经写入。Sourcetree 里显示的当前用户也会同步这个值。这里要注意邮箱不一定是真实的邮箱但最好是你常用的邮箱因为开源项目或企业内部代码评审时其他人看到的就是这个邮箱。5.2 SSH 密钥别再用旧教程里的 RSA 了Sourcetree 要往 GitHub、GitLab 或公司私有仓库推送代码最常用的认证方式不是用户名密码而是 SSH 密钥。很多老教程还在教用 RSA 2048 生成密钥但 GitHub 等平台已经不再接受某些老的加密算法现在更推荐用 ED25519。这也对应了很多人搜的“sourcetree ed25519”。在 Windows 上生成 ED25519 密钥的方式ssh-keygen -t ed25519 -C 你的邮箱它会问保存文件的路径和口令口令可以留空也可以设置。设置了口令之后Sourcetree 每次连接远端可能都会要求输入口令不设口令则免密连接安全性略低但本地开发更顺。生成之后你会得到两个文件私钥默认id_ed25519和公钥默认id_ed25519.pub。私钥千万别外传公钥可以随便复制。复制公钥内容Windowsnotepad $env:USERPROFILE\.ssh\id_ed25519.pubmacOScat ~/.ssh/id_ed25519.pub然后在 GitHub 的 Settings - SSH and GPG keys 页面把公钥内容粘贴进去保存。GitLab 则在 Preferences - SSH Keys 里做同样操作。5.3 Sourcetree 里如何让 SSH 密钥生效Sourcetree 启动时会自动读取系统 SSH 配置和默认密钥对一般情况下不需要手动在 Sourcetree 里导入密钥。但很多人照着网上教程在 Sourcetree 的“Tools - Options - Authentication”标签里点来点去找“导入 SSH 密钥”按钮反而把自己搞晕了。更稳妥的做法是先用命令行测试 SSH 连通性。ssh -T gitgithub.com如果看到Hi username! Youve successfully authenticated说明 SSH 密钥已经生效。这时再打开 Sourcetree 去克隆仓库它会直接从系统 SSH 里读出密钥不需要额外配置。如果命令行测试一直提示 Permission denied那问题大概率出在密钥生成或添加方式上而不是 Sourcetree。回到第 5.2 节重新生成并在远端重新添加公钥即可。5.4 HTTPS 协议还是 SSH 协议在 Sourcetree 克隆仓库时会让你填仓库地址。地址有两种HTTPS形如https://github.com/xxx/xxx.git需要每次输入账号密码或登录令牌SSH形如gitgithub.com:xxx/xxx.git依赖密钥认证我的建议是如果只是偶尔使用HTTPS 搭配账号令牌最省事如果经常推送代码用 SSH 密钥最顺畅。Sourcetree 对两种协议都支持不用额外装插件。需要切换协议时重新克隆一次或者修改已有仓库的远端地址即可。6. 装完之后先别急着推代码验证这几个环节6.1 本地仓库和远程仓库各建一个跑通完整流程Sourcetree 装好了配置也做好了怎么确认一切正常我建议做一次最小验证“新建一个本地仓库提交一次克隆一个远程仓库推送一次”。本地仓库验证很简单在 Sourcetree 里点击“Create”按钮选择一个空文件夹它会自动执行git init并初始化仓库。随后创建一个测试文件比如 README 或者任意文本Sourcetree 会一次性把它显示在“未暂存区域”。点上“暂存全部”再写上提交信息点“提交”第一次本地提交就算完成了。这一步能确认 Git 底层工作正常、Sourcetree 的提交链路没问题。6.2 克隆远程仓库验证认证和网络下一步在 GitHub 上随便建一个空仓库复制 SSH 地址然后在 Sourcetree 里选择“Clone”按钮。粘贴地址之后Sourcetree 会解析仓库信息默认把克隆目标目录放在你设置的仓库根目录下。如果地址、权限都没有问题进度条走完本地就会出现这个仓库远端分支也会一清二楚。这里有个常见误区克隆时如果提示“Host key verification failed”是因为你第一次连接该远程主机SSH 会询问是否信任对方的主机指纹。在命令行下需要输入 yes在 Sourcetree 里则可能弹出确认框。很多人看到“fingerprint”之类的词以为是安全警告直接点了否或取消结果就永远连不上。正确做法是确认指纹后选择信任。6.3 常见报错对照表我把安装和使用初期比较容易遇到的报错整理成一张表方便对照报错或现象原因处理方式打开提示“用户设置必须被修复”全局 Git 配置缺失或异常点击修复填写用户名和邮箱或在命令行执行git config --global手动设置克隆时提示 Unable to connect / 超时网络限制或代理冲突检查网络代理设置Sourcetree 的 Tools - Options - Network 可调整代理找不到 Git 可执行文件未安装 Git 或安装时未加入 PATH单独安装 Git for Windows并在 Sourcetree 首选项中指定 git.exe 路径Host key verification failedSSH 首次连接未信任主机指纹在确认指纹无误后选择信任并继续推送到远端口令认证失败使用 HTTPS 且令牌过期重新生成访问令牌并让 Sourcetree 重新认证6.4 安装后的几个设置建议Sourcetree 默认配置能跑通大部分场景但有几个地方我会在装好后立刻调整默认克隆目录在 Tools - Options - General 里设置一个专门的 GitRepos 目录避免仓库散落得到处都是。墓碑行Diff 设置在 Diff 标签页里可以调整文本比较工具比如把外部比较器设置为 Beyond Compare代码对比会更直观。Sourcetree 自带的比较面板够用但大冲突时外部工具更好用。二进制文件过滤在 Preferences 或设置里把图片、压缩包这类二进制文件标记为不参与 diff每次提交时 Sourcetree 就不会把二进制文件的变化内容硬列出来页面干净很多。这些设置都不影响 Git 底层行为纯粹是使用体验层面的优化早点设置好后面省心。6.5 Windows 11 下的两个细节如果你的系统是 Windows 11装完 Sourcetree 后我建议顺手做两件事一是检查 Windows 的“开发者模式”是否开启。开发者模式允许系统更灵活地处理符号链接和长路径某些前端项目克隆下来会创建很长的文件路径不开这个功能可能克隆到一半报错。开启方式设置 - 隐私和安全性 - 开发者选项打开“开发人员模式”。二是把 Sourcetree 设为 Git 默认的图形工具。Windows 11 的“设置 - 应用 - 默认应用”里按文件类型或协议进行关联虽然 Sourcetree 需要你手动指定但设置好之后以后双击.git相关配置或点击仓库里的快捷方式都会直接唤起 Sourcetree体验好不少。最后再分享两个小建议第一装完 Sourcetree 之后别急着把命令行扔掉。我见过不少同事只用图形界面提交代码遇到冲突时点几个按钮解决不了最后还得靠命令行来恢复。图形化工具能帮你建立概念但不要让它变成你的舒适区。至少git status、git log、git remote -v这几个命令要看得懂、用得起来。第二Sourcetree 大部分诡异问题都是“本地 Git 环境不干净”导致的而不是软件本身的问题。所以安装过程里凡是遇到关于 Git 的提示认真看一下能沿用系统 Git 就沿用能修复用户设置就修复别慌着重装。把环境弄干净Sourcetree 用起来真的可以很顺手。
