Claude Code 前置条件：Git 安装与配置全指南

Claude Code 要跑起来，第一件事不是装它本身，而是把 Git 这个地基打牢。很多人装 Claude Code 时卡在第一步，报错信息五花八门，其实根子上就是 Git 没装对、没配好，或者环境变量压根没生效。这篇我把 Git 的安装、配置、验证到和 Claude Code 对接的每个步骤都拆开讲清楚，基于我在多台机器（Windows、macOS、Linux）上的实际安装经验，把那些文档里不会写的坑也一并交代。

1. 为什么 Claude Code 必须先装 Git：版本控制的底层逻辑

1.1 Claude Code 的定位：终端里的 AI 编程搭档

Claude Code 是 Anthropic 推出的命令行编程代理工具，你可以在终端里直接跟它对话，让它读代码、改代码、跑测试、提交代码。它本质上是一个跑在终端里的智能体，能主动操作文件系统、执行命令、调用各类开发工具链。你不用再在 IDE 里复制粘贴报错信息，而是直接以自然语言描述需求，它会在你的项目里完成整套操作。

但这里有个很多人第一次接触时不理解的点：Claude Code 对项目的理解方式极度依赖 Git。你去翻 Anthropic 的官方文档，安装前置条件里明确写着需要 Git 2.x 以上。为什么会这样？因为 Claude Code 在工作时需要频繁查看项目的变更历史、对比当前修改、撤销错误操作。这些能力全部建立在 Git 仓库的基础上。没有 Git，Claude Code 就像一个没有短期记忆的助手，它无法感知你改了哪些文件、哪些改动需要保留、哪些需要回滚。

1.2 Git 在 Claude Code 工作流中的三个关键作用

我在实际使用中，总结出 Git 对 Claude Code 最重要的三个支撑点。

第一，变更感知能力。Claude Code 会通过 git status、git diff 这些命令来了解项目当前的状态。你和它说"帮我看看最近改了什么"，它实际执行的就是 git log 和 git diff。如果 Git 没装好或者配置不完整，这些操作全部会失败，Claude Code 会直接报错或者表现得"很蠢"。

第二，安全回滚机制。Claude Code 修改代码时可能有失误，官方推荐的工作方式就是让它频繁创建提交或至少保持工作区干净。你在使用中会发现，Claude Code 执行关键操作前经常会问你要不要先 commit 一次，它自己也会善用 git stash 和 git checkout 来做保险。这套机制没有 Git 是转不起来的。

第三，身份认证基础。Claude Code 在将代码推送到远程仓库（比如 GitHub、GitLab）时，需要调用 Git 的认证体系。SSH key 或 HTTPS token 都是通过 Git 配置层关联到系统的。你提前把 Git 身份配置好，Claude Code 推送代码时才不会反复弹认证框。

1.3 这篇教什么：从零到能跑 Claude Code 的第一级台阶

这篇文章是 Claude Code 安装系列的第一篇，只聚焦一件事：把 Git 装好、配好、验证通。文章里面提到的其他前置条件（Node.js 环境、Claude Code 本体安装、API Key 配置），后面会单独开篇。不过我可以先给你画个全貌图，方便你心里有数：

• 第一步：安装 Git（本文内容）
• 第二步：安装 Node.js 18 以上版本
• 第三步：通过 npm 安装 Claude Code（npm install -g @anthropic-ai/claude-code）
• 第四步：运行 claude 命令，完成认证和配置

每一步都有各自的坑，但 Git 是地基中的地基。Git 装不好，后面所有报错你都会误判成 Claude Code 本身的问题，排查起来会非常痛苦。

2. 装 Git 之前的准备工作：版本、平台、安装方式怎么选

2.1 Git 版本怎么挑：别追新，也别太老

Git 的版本迭代很快，但对你和 Claude Code 来说，只要满足 2.x 版本就可以。Claude Code 官方文档要求的底线是 Git 2.0 以上，实测中 2.30 以上基本没有任何兼容问题。我不建议刻意追求最新版本，因为某些新版本如果有 bug，反而会引入不必要的变量。我自己的原则是：Windows 和 macOS 上直接下载官方最新的稳定版，Linux 上用系统自带源里的版本。

这里有个细节值得注意：安装完 Git 后一定要确认版本号。你可能会觉得这是废话，但我遇到过很多次用户反馈"我明明装了 Git"，结果一查 git --version 提示找不到命令。大概率是装完之后没刷新终端，或者是安装过程被安全软件拦截了。确认版本号的命令很简单：

bash复制git --version

如果输出类似 git version 2.39.2 (Apple Git-XXX) 或者 git version 2.34.1 这样的信息，就说明安装成功且命令能被正常找到。如果提示 command not found，往下看第三章各平台的排查方法。

2.2 三种安装方式对比：图形安装包、包管理器、编译安装

Git 的安装方式大致分三类，我分别说下适用场景。

第一种是官方安装包，就是去 Git 官网下载对应平台的安装程序。这种方式最直观，图形界面点下一步就行，特别适合 Windows 用户和 macOS 新手用户。缺点是后续升级要重新下载安装包。

第二种是包管理器安装。macOS 上用 Homebrew（brew install git），Windows 上用 winget 或 Chocolatey（winget install --id Git.Git -e --source winget），Linux 上用 apt/yum/dnf。这种方式的好处是升级方便（一条命令搞定），能自动处理依赖，而且装出来的 Git 与系统集成度更高。我之前给朋友远程装机时，用 winget 一条命令就搞定了 Windows 上的 Git，比手动下载安装包快多了。

第三种是源码编译安装。这种方式我一般不建议，除非你要定制某些编译参数。Git 依赖的库比较多（curl、zlib、openssl 等），源码编译容易遇到依赖版本不匹配的问题，折腾成本高，收益却几乎没有。只有嵌入式环境或极其特殊的服务器才需要考虑这条路。

2.3 下载渠道：官方源和备用源

安装包获取渠道是个容易被忽略的问题。因为网络环境不同，很多人访问 Git 官网下载页面时速度不稳定，甚至页面都打不开。我的建议很简单：优先官方渠道，卡住了再换备用渠道。

• 官方地址：https://git-scm.com/downloads，这里有 Windows、macOS、Linux 各平台的下载入口
• Windows 备用：国内不少高校和云厂商提供了 Git for Windows 的镜像，搜索"Git for Windows 镜像"就能找到，下载速度通常很快
• macOS 备用：如果 Homebrew 安装时下载慢，可以配置国内的 Homebrew 镜像源，把 HOMEBREW_BOTTLE_DOMAIN 环境变量指到镜像地址即可
• Linux 备用：如果系统默认源里的 Git 版本太老，可以添加 Git 官方维护的 PPA（Ubuntu 系）或使用第三方源

注意：下载安装包时要注意校验文件哈希或者至少确认文件名和文件大小是否与官网一致。防的是下载到被篡改的安装包，尤其是从非官方渠道下载的时候，别只图快。

3. 三大平台安装 Git 完整实操：每一步都给你讲透

3.1 Windows 平台：官方安装包图文级拆解

Windows 上安装 Git，最稳的还是官网的 Git for Windows 安装包。整个安装过程全是图形界面，但我见过太多人在安装向导里一路狂点"Next"，结果装完之后发现右键菜单里多了一堆不想要的东西，或者 shell 集成乱七八糟。所以我把每个关键步骤拆开讲。

第一步，下载安装包。去 https://git-scm.com/downloads，页面会自动识别你的操作系统，点击 Windows 下的下载按钮即可。建议选择 64-bit 版本，除非你的电脑还是远古时代的 32 位系统。

第二步，双击运行安装包，选择安装路径。这里我建议保持默认路径，也就是 C:\Program Files\Git。不要为了省 C 盘空间改到中文路径或者带空格的路径，后面有些工具解析起来容易出幺蛾子。选择组件时，默认勾选基本够用，但建议额外确认下面这几项：

• Git LFS 勾上。Claude Code 处理项目时经常涉及大文件场景，提前装好 Git LFS 能避免后续处理大文件时报错。
• Associate .git configuration files* 和 Associate .sh files 建议勾上，方便后续直接用 Git Bash。
• Check daily for Git for Windows updates 看个人喜好，我一般去掉，因为用 winget 更新更统一。

第三步，到"Select Start Menu Folder"页面，直接 Next。到了 "Choosing the default editor used by Git" 这步就要注意了，默认是 Vim。对不熟悉 Vim 的初学者来说，一旦哪天误触了 git commit 进入 Vim 编辑器，会卡在里面不知道如何退出。我建议把默认编辑器切换成 Notepad++ 或 VS Code，如果这两个都没有，就用默认的 Vim 也没关系，学会 :wq 退出就行。

第四步，Adjusting your PATH environment 这步是重中之重。可选三个选项：

• Use Git from Bash only：只在 Git Bash 里能用 git 命令，不推荐
• Git from the command line and also from 3rd-party software（推荐）：把 git 加到系统 PATH 中，CMD、PowerShell、Claude Code 都能调用
• Use Git and optional Unix tools from the Command Prompt：会覆盖 Windows 自带的一些 Unix 工具，可能导致系统命令行为改变，不推荐

一定要选第二项。我遇到过不少小伙伴装完 Git 后，在 CMD 或终端里输入 git 提示找不到命令，就是这里选成了第一项。

第五步，HTTPS 传输后端选择。默认是 "Use the OpenSSL library"，这个保持默认就好，不用动。换行符转换选择 "Checkout as-is, commit Unix-style line endings"，也就是默认第二项，这在跨平台协作时问题最少。其余窗口全部保持默认，一路 Next 完成安装。

装完之后，重启一下你的终端（CMD 或 PowerShell），再执行：

bash复制git --version

如果输出版本号，恭喜你，Windows 上的 Git 已经装好了。如果还是提示找不到命令，去"系统属性 → 环境变量"里确认 C:\Program Files\Git\bin 是否在 PATH 里，没有就手动加进去，然后重新打开终端。

3.2 macOS 平台：两者取其一就够了

macOS 上的 Git 安装路径有两条，我推荐直接用 Homebrew。

如果你还没装 Homebrew，先去装它，这是 macOS 开发者的基础设施工具。终端执行：

bash复制/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

装完 Homebrew 后，一行命令就能装 Git：

bash复制brew install git

安装完成后执行 git --version，如果系统里原本就有 Apple 自带的 Git（版本号通常像 2.39.2 (Apple Git-145)），执行 which 会显示 /usr/bin/git。这里容易踩坑：Homebrew 装的 Git 在 /usr/local/bin/git（Intel Mac）或 /opt/homebrew/bin/git（Apple Silicon），你需要确认终端实际调用的是哪一个。我用 Apple Silicon 的 Mac 时，就遇到过终端里显示的版本是 /usr/bin/git，这意味着我 brew 装的 Git 没有优先被使用。

解决办法是调整 PATH 顺序，让 /opt/homebrew/bin 排在 /usr/bin 前面。在 ~/.zshrc 里加上：

bash复制export PATH="/opt/homebrew/bin:$PATH"

然后执行 source ~/.zshrc 让其生效。再执行 which git，如果输出变成 /opt/homebrew/bin/git，就说明 Homebrew 版 Git 接管了。

不过这里说句公道话，Apple 自带的 Git 其实也够用。如果你的 mac 系统较新，自带的 Git 版本已经在 2.39 以上，那 brew install git 这步完全可以跳过。Claude Code 对 Git 版本要求并不苛刻。

3.3 Linux 平台：用系统包管理器解决

Linux 装 Git 是所有平台里最省心的，因为绝大多数发行版都预装了 Git，或者软件源里直接就能装。分发行版来看。

Debian/Ubuntu 系：

bash复制sudo apt update
sudo apt install git -y

Red Hat/CentOS/Fedora 系：

bash复制sudo yum install git -y
# 或者新版 Fedora 用
sudo dnf install git -y

Arch Linux 系：

bash复制sudo pacman -S git

装完照例验证 git --version。如果系统源里的 Git 版本太老（比如 Ubuntu 18.04 的默认源还停留在 2.17），而你又非要新版本，可以添加 Git 官方 PPA：

bash复制sudo apt-add-repository ppa:git-core/ppa
sudo apt update
sudo apt install git -y

但我的建议是，除非有明确需求，否则系统源版本就够了。Claude Code 要的是 Git 2.x，老的 2.17 也能正常工作。折腾版本升级反而可能引入依赖问题。

Linux 上还有一个小坑值得说：有些精简版的云服务器镜像里没有安装 git，你执行 git --version 会提示命令不存在。这时候别慌，用系统包管理器装一下就行，实际上云服务器的默认软件源里都有 git。另外，如果你用的是从零编译出来的极简系统，可能需要额外安装 ca-certificates 包，否则 Git 访问 HTTPS 仓库时会因为证书问题报错。

4. 装完不等于配好：Git 的三层基础配置

4.1 身份信息：提交代码的第一张通行证

Git 装好后，第一件事就是配置用户名和邮箱。这一步不做，你 git commit 的时候会报错或者被 Claude Code 以一堆乱码身份提交。验证方式很直接：

bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

这里的邮箱建议和你 GitHub/GitLab 账号绑定的邮箱保持一致，这样你的提交记录才能正确关联到账号头像和主页。我自己就吃过亏：早期在公司电脑上随意配了个邮箱，结果 GitHub 上那些提交全都显示成一个灰色的"未知用户"，后期梳理项目贡献记录时非常痛苦。

检查配置是否生效：

bash复制git config --global --list

输出结果里应该能看到 user.name 和 user.email。配置存放在 ~/.gitconfig 文件里，你直接用文本编辑器打开也能看到。

4.2 SSH 密钥：打通远程仓库的钥匙

Claude Code 在完成和远程仓库的交互时，大概率需要 SSH 认证。生成 SSH key 的命令如下：

bash复制ssh-keygen -t ed25519 -C "你的邮箱"

一路回车即可，默认生成在 ~/.ssh/id_ed25519。生成的公钥在 ~/.ssh/id_ed25519.pub，你需要把它添加到 GitHub 或其他代码托管平台的 SSH keys 设置里。

这个环节我有几个实际操作中的提醒。

第一，优先用 ed25519 而不是 RSA。ed25519 是目前推荐的加密算法，生成的密钥更短、安全性更高、验证速度更快。只有当你连接的是一些老旧的 Git 服务器（比如某些公司内部自建的老系统），才需要用 RSA 兼容。

第二，生成密钥时如果遇到 "Enter passphrase" 提示，建议设置一个密码。虽然每次 push 都要输密码有点麻烦，但这是保护私钥的最后一道防线。你也可以用 ssh-agent 配合 ssh-add 把密钥加载到内存里，这样就可以只输入一次密码。

第三，添加公钥后一定要测试连接：

bash复制ssh -T git@github.com

如果是 GitHub，看到类似 Hi username! You've successfully authenticated, but GitHub does not provide shell access. 就说明认证通过。如果权限报错，多半是公钥没复制完整或者平台没识别出来，检查一下复制公钥时有没有把换行符弄丢了。

4.3 常用核心配置：拆开讲几个省心参数

除了身份信息，我建议你把下面这几个参数也一次性配好，省得后面 Claude Code 调用 Git 时频繁出问题。

默认分支名。新版 Git 初始化仓库时默认分支名已经从 master 改为了 main（取决于版本），但我见过不少老版本还是 master。统一设置成 main 可以避免很多困惑：

bash复制git config --global init.defaultBranch main

提交时自动转换换行符。跨平台协作时，Windows 和 Linux/macOS 的换行符不一致是常见的坑。我推荐统一使用：

bash复制git config --global core.autocrlf input

简单解释一下：input 的意思是提交时把 CRLF 转成 LF，checkout 时不做转换。在 macOS/Linux 上这是最稳妥的配置。Windows 上我推荐 core.autocrlf true，这样 checkout 时会自动转成 CRLF，提交时又会转回 LF。

长路径支持。Windows 上 Git 默认对超过 260 字符的路径处理不好，而现代前端项目（尤其是 node_modules 目录）长路径非常多。建议执行：

bash复制git config --global core.longpaths true

这个参数虽然小，但能帮你避免很多莫名其妙的 checkout 失败。

默认编辑器。如果之前没在安装向导里改，也可以在终端配置：

bash复制git config --global core.editor "code --wait"

这样 git commit 时打开的是 VS Code。如果你的环境里没有 code 命令，也可以换成 notepad++ 等其他编辑器。

提交模板和别名是进阶选项，这里不多说。等 Claude Code 工作流跑起来了，你有的是时间慢慢调。

4.4 Git Bash 和系统终端：Windows 用户的额外一课

Windows 上装完 Git 会附带一个 Git Bash，这是一个模拟 Unix 环境的终端。Claude Code 在我的 Windows 机器上跑，实际上我都是直接在 Git Bash 里运行它，原因有两个。

第一，Git Bash 对 Git 命令的兼容性最好。Windows 自带的 CMD 和 PowerShell 在处理某些 Git 输出格式、路径分隔符时，会出现转义问题。Git Bash 里就是原汁原味的 Unix 风格，和 Claude Code 的指令交互更顺畅。

第二，Claude Code 内部会调用很多 Unix 工具（比如 grep、sed、cat），这些在 Git Bash 里天然可用，在 CMD 里则可能找不到。

所以 Windows 用户我的建议是：以后跑 Claude Code 都打开 Git Bash。如果你觉得 Git Bash 的默认样式丑，可以去 Windows Terminal 里配置 Git Bash 作为 profile，体验会好很多。

5. 收尾验证：确保 Git 能正常对接 Claude Code

5.1 一条命令完成环境自检

Git 配完之后，做一次完整的环境自检。在终端执行：

bash复制git --version
which git
git config --global --list
ssh -T git@github.com

如果这四条命令都能正常输出，你的 Git 环境基本就合格了。我自己在帮别人排查 Claude Code 安装问题时，第一步就是让他贴这四条命令的输出。很多时候问题就出在 which git 指向了错误路径，或者 ssh -T 认证失败。

5.2 Claude Code 对 Git 环境的最小要求

简单总结一下，Claude Code 实际运行中对 Git 的最小要求只有三点：

• git 命令可以被终端正常解析（PATH 正确）
• git 用户身份已配置（user.name 和 user.email 非空）
• 与远程仓库的认证通道可用（SSH 或 HTTPS token）

满足这三点，你就可以继续走上 Claude Code 本体的安装了。很多人卡在最后一步认证上，这里多说一句：如果你使用 HTTPS 方式克隆仓库，Git 可能会要求输入账号密码，现在 GitHub 已经不再支持密码认证，你需要用 Personal Access Token 代替密码。在你第一次 push 时，Git 会提示输入 token，粘贴进去即可。

5.3 和 Claude Code 的第一次握手

等 Git 环境全部就绪，后续安装完 Claude Code 后，你会需要一个项目目录作为测试环境。建议新建一个空目录并初始化 Git 仓库：

bash复制mkdir test-claude
cd test-claude
git init

这个干净的仓库是验证 Claude Code 和 Git 协作的最理想场所。你可以在里面新建一个测试文件，模拟一次 commit，让 Claude Code 感知项目状态的变化。如果一切都通畅，说明 Git 这个地基算是真正打牢了。

6. 高频踩坑实录：Git 安装和配置常见问题速查

6.1 安装失败或无法使用的典型场景

我在实际教学中收集了不少高频问题，整理成一张速查表方便你排查。

最后一个注意，http.sslVerify false 这条一定要慎用，它会关闭 HTTPS 证书校验，有中间人攻击风险。我只有在调试时临时关闭，排查完成后立即恢复。

6.2 配置层面最容易忽视的细节

配置 Git 时，有几个细节很容易被忽略但影响很大。

第一个是全局配置和仓库配置的优先级。Git 的配置分三个层级：系统级、全局级、仓库级。优先级依次是仓库级 > 全局级 > 系统级。这意味着如果你在某个仓库里单独设置了 user.email，它会覆盖全局配置。遇到提交身份不对的情况，先到仓库目录里执行 git config --list --local 看看是不是仓库级配置在作怪。

第二个是换行符配置要统一。如果你在 Windows 和 macOS 之间来回切，换行符配置不一致会导致整个文件在 diff 里显示为全量变更。我见过太多人因为这问题满屏都是红色绿色的 diff，实际内容一行都没改。正确做法是团队内统一约定，Windows 用 core.autocrlf true，macOS/Linux 用 core.autocrlf input。

第三个是代理配置不要随便填。有些时候你为了加速网络访问，可能给终端配置了代理环境变量。Git 会自动读取这些变量。如果你配置的代理失效了，会看到仓库访问报 Failed to connect。排查这类问题时，先检查环境变量里有没有 http_proxy/https_proxy，或者 Git 配置文件里有没有 http.proxy 设置。

6.3 给 Windows 用户的额外提醒

Windows 上装 Git 还有几个容易被盯上的点，我单独说。

右键菜单问题。Git for Windows 默认会在右键菜单添加 "Git GUI Here" 和 "Git Bash Here"。如果你觉得菜单太冗余，可以在安装向导里取消 "Windows Explorer integration" 选项，或者在安装后通过设置面板调整。

杀毒软件拦截问题。Windows Defender 偶尔会误报 Git 的某些组件，特别是首次运行时。如果安装后 git 命令执行缓慢或被拦截，可以在 Windows 安全中心的"排除项"里把 Git 安装目录加进去。

终端编码问题。在中文 Windows 上，Git 输出中文文件名可能显示成 \346\265\213 这样的转义序列。这不是错误，是 Git 默认对非 ASCII 字符做了转义。想要正常显示中文，可以执行：

bash复制git config --global core.quotepath false

这个配置我在实际工作中必开，否则看中文文件名一圈乱码，Claude Code 读文件列表时也容易困惑。

6.4 我来分享几个实战排查思路

排查 Git 配置问题，我自己的方法论是从新到旧、从全局到局部。先把问题复现一遍，确认具体报错内容，然后通过 git config --list 看当前生效的配置，再检查 PATH 和 SSH agent 状态。90% 的 Git 配置问题都能在这三步里找到答案。

另外一个经验是：报错信息永远是第一线索。Git 的报错其实写得非常清楚，但很多人看到英文就慌。建议把报错信息复制粘贴到搜索引擎里，大概率前面几条结果就有答案。我在写这篇文章之前，特意去翻了一圈近期关于 Git 安装失败的常见报错，发现十有八九都是 PATH 没配对或者 SSH key 没生效这两个原因。

7. 从 Git 到 Claude Code：如何把地基真正用起来

Git 装好配置好之后，不要急着去注册各种服务。先在你的机器上把 Git 的基础操作练一遍，比如初始化仓库、创建文件、提交改动、查看日志、拉取远程代码。这些操作没有练熟，后面 Claude Code 给你生成了一大堆修改你却看不明白它在干什么，会很被动。

这里我给出一个自测练习流程：在终端新建一个临时仓库并完成一轮完整提交。

bash复制mkdir git-practice
cd git-practice
git init
echo "hello git" > readme.md
git add readme.md
git commit -m "first commit"
git log --oneline

如果输出里能看到 first commit，说明 Git 的安装和身份配置已经完全打通，Claude Code 运行所需的环境条件已经满足。如果卡在 git commit 这一步，优先检查 user.name 和 user.email 是否配置正确。

从这一步开始，整个 Claude Code 安装流程的地基就打好了。后面装 Node.js、装 Claude Code 本体都是在这个基础上进行的。我在实际使用中最大的感悟是：Git 环境的稳定与否，直接决定了 Claude Code 用起来顺不顺手。那些用 Claude Code 时频繁遇到"操作无法完成"的情况，回头查基本都是 Git 环境有暗病。所以这一篇别看只是安装和配置，值得你认真对待。

最后再分享一个我的个人习惯：每次在新机器上配置 Git，我都会把 4.3 节里那几个核心参数（init.defaultBranch、core.autocrlf、core.quotepath、core.longpaths）一次性配好，而不是等出了问题再回头补。配好这些参数后，后续和 Claude Code 协作的体验会顺畅很多。下一篇我会接着讲 Node.js 环境的准备和 Claude Code 的安装，到时候我们继续。