最近在折腾Claude Code的时候我发现一个特别有意思的现象卡住最多人的地方反而是一个跟AI没什么关系的基础依赖——Git。随便翻翻社区就能看到一堆人在问git : 无法将git项识别为cmdlet、函数、脚本文件或可运行程序的名称或者折腾了半天Claude Code还是跑不起来最后发现是Git环境压根没弄对。这篇是Claude Code安装系列的第一篇先把地基打好把Git装对、装完、配好。后面再跑Claude Code就不会被各种莫名其妙的环境问题反复折腾。Claude Code作为终端里的AI编程助手它本质上是代替你在命令行里执行编码任务而编码任务绕不开版本管理。所以这篇文章不会只讲下载一个Git安装包然后下一步下一步而是会把每个安装选项背后的影响、装完之后的验证方法、以及接上Claude Code之前最容易踩的坑全部过一遍。不管你是一点命令行基础都没有的新手还是准备帮同事配环境的工具人都可以照着一步步操作。1. 为什么Claude Code的安装总是绕不开Git1.1 Claude Code的工作模式它靠Git做大量底层操作很多人有个误区觉得Git只是程序员用来备份代码的工具自己就是想让Claude Code写点小脚本、跑个自动化根本用不上Git。这个想法恰恰是后面一堆报错的根源。Claude Code在运行时需要频繁读取当前代码仓库的状态查看工作区有哪些文件发生了变化、对比文件之间的差异diff、生成提交commit、切换分支、批量修改文件后自动提交等等。这些操作底层全部是通过Git命令来实现的。换句话说Claude Code不是把Git当成一个可选插件而是当成运行依赖。如果机器上根本找不到Git或者Git没被正确加进PATH环境变量Claude Code启动后连最基本的文件状态都读不到轻则功能残缺重则直接报错退出。我用一个比较粗糙但很好理解的类比Claude Code像个经验丰富的施工监理而Git是给它提供地基数据的测量员。测量员不在场监理再聪明也只能干瞪眼。1.2 动手前先查一遍系统里到底有没有Git在下载安装包之前花一分钟检查系统里是不是已经存在Git。尤其是装过VS Code、Android Studio、或者某些游戏引擎的朋友电脑里很可能已经带着一份Git了只是你自己完全没注意过。Windows下按WinR输入cmd回车在命令行里敲git --version如果输出类似git version 2.47.0.windows.1这样的信息说明Git已经存在。这时候再看一眼版本号如果主版本号还停留在2.30以下我建议重新装一个新版。Claude Code对Git版本的兼容策略会持续迭代旧版本在特定操作下容易遇到奇怪的兼容性问题没必要在这些地方省事。如果系统提示git不是内部或外部命令或者PowerShell弹出无法将git项识别为cmdlet、函数、脚本文件或可运行程序的名称那就说明确实没装或者装了但Git的可执行目录没进PATH。遇到这种情况直接跳到下一章开始安装就好。另外顺手确认一下系统平台。Windows 10/11基本都选64位版本。怎么看系统位数右键此电脑→属性在系统类型一行就能看到。现在还坚持用32位系统的情况已经非常少了如果你真是32位后面的Claude Code大概率也会碰到其他问题建议先把系统升级到64位再继续。2. Windows下Git的完整安装过程2.1 下载环节版本与渠道怎么选Git的Windows版本主要有两种形态一种是官方维护的独立安装包文件名类似Git-2.47.0-64-bit.exe另一种是便携版PortableGit解压即用不用安装。日常使用我强烈建议选安装版而不是便携版原因很实际安装版会自动帮你写好右键菜单、PATH环境变量、文件关联等一堆基础设置省去手动配置而便携版需要自己把bin目录加进PATH多一步就多一个出错机会。Claude Code从终端启动时找的是PATH里的git.exe便携版这种形态对新手来说纯属给自己挖坑。下载渠道认准Git官方站点就行。那个页面上有Windows、macOS、Linux各平台的下载入口Windows下面直接选64-bit版本。页面里还会放一个.sig结尾的签名校验文件普通用户不用管它直接下载exe安装包即可。整个安装包大概五六十MB。下载慢多半和网络环境有关换个时段再试或者从你所在地区访问更快的镜像渠道获取都比干等着强。在双击安装包之前建议先退出正在运行的编辑器、IDE和其他命令行工具。原因是Git安装过程会修改系统PATH变量如果有程序一直占用着PATH可能导致安装程序写入失败或者旧进程还读着旧配置结果装完以后打开终端一敲命令还是提示找不到git。等安装结束之后重新打开工具才能读到新的环境变量。2.2 安装向导逐项选型每个选项的取舍理由安装包启动后前几步基本都是Next真正需要停下来动脑的是中间几个关键界面。很多人习惯全程Next装完以后发现Claude Code调用Git时行为诡异就是因为没在下面几个选项上做取舍。第一屏是组件选择Select Components。默认会勾选Git Bash HereGit GUI Here和Git LFS。建议保持默认同时把Add a Git Bash Profile to Windows Terminal也勾上这样你在Windows Terminal里可以一键打开Git Bash后面配合Claude Code很顺手。第二屏是选择默认编辑器Default editor used by Git。默认的Vim对新手极不友好一旦git commit触发了编辑器就会卡在那个黑屏界面里不知道如何退出。建议安装时直接选Use Visual Studio Code as Gits default editor前提是你已经装了VS Code。如果还没装选Notepad或者Nano也可以。这个设置之后能改但安装时一步到位最省心。第三屏是调整PATH环境变量Adjusting your PATH environment。这是全场最关键的一屏。默认选项是Git from the command line and also from 3rd-party software我建议保持默认。上面的Use Git and optional Unix tools from the Command Prompt会把一堆Unix命令也注入PATH容易和Windows自带命令产生冲突新手不建议选。最下面那个Use Git from Git Bash only是最坑的选项选了之后PowerShell和CMD里找不到git命令Claude Code基本没法工作千万别选。后面还会遇到换行符转换和终端模拟器两个选项。终端模拟器我建议选Use Windows default console window也就是使用Windows自带控制台窗口如果选MinTTY窗口更漂亮但某些脚本处理ANSI转义序列时会出现乱码或格式错位。换行符那项选默认的Checkout Windows-style, commit Unix-style line endings即可这套规则在跨平台协作时最不容易出问题。2.3 装完之后的环境变量刷新安装向导跑完点击Finish时安装器通常会默认打开一个新终端窗口。这一步很重要安装程序对PATH的修改只对之后启动的进程生效。安装器帮你开的新窗口读到的是新PATH但你之前已经开着的旧CMD或PowerShell窗口里还是旧PATH。所以如果你手头开着旧终端直接关掉重开别图省事在旧窗口里继续验证。如果重新打开终端后git --version还是报错别急着卸载重装。先检查一下安装时是不是选了Use Git from Git Bash only那会导致Git的可执行目录根本没进系统PATH。或者到系统设置里搜索编辑账户的环境变量打开用户变量的Path看看里面是否包含Git的cmd目录。正常安装后应该有类似C:\Program Files\Git\cmd这一条。没有就手动加上再重启终端。3. 装上之后怎么确认它真的能用3.1 在Git Bash与PowerShell里分别做验证装完Git以后很多人只在Git Bash里验证一下版本号就感觉大功告成结果等Claude Code报错时才发现PowerShell里根本调用不了Git。所以验证要分别做先打开Git Bash输入git --version确认Git Bash环境正常再打开PowerShell或CMD同样输入git --version确认系统级PATH生效。两步都通过才算真正装好。我还会顺手多跑一个更严格的检查确认Git的实际路径where gitPowerShell里用Get-Command git效果类似。这个检查的价值在于它能输出系统实际会调用的git.exe路径。如果输出的是C:\Users\你的用户名\AppData\Local\Programs\Git\cmd\git.exe这种用户级安装路径没问题但如果输出一堆同名的git命令分属不同目录就要留意先后顺序。排在前面的会被优先调用顺序不对就会出现在A目录装的Git版本和B目录不一样这种让人头大的问题。3.2 多Git客户端共存时的优先级问题电脑里很可能不止一个Git。常见情况包括VS Code自带一份Git for WindowsAndroid Studio的Native Terminal可能带GitTortoiseGit小乌龟可能要求系统预装一份Git还有通过其他工具链带进来的。多个Git并存本身不可怕可怕的是版本不一致Claude Code在不同终端里读到的Git行为不一样排查问题时很容易被误导。我处理多Git客户端共存的经验是确定一个主版本并确保它在PATH里排第一位。所谓主版本就是你从官方下载安装的那个版本或者是你想长期使用的版本。然后打开系统环境变量编辑器把其他Git相关条目从用户变量和系统变量的Path里移除或后移。注意移除前先想清楚有些软件比如TortoiseGit可能依赖特定路径下的Git贸然删掉可能让软件失灵。不过在我实测中只要主版本本身可用绝大多数依赖Git的命令行工具和图形客户端都能正常工作。3.3 升级或重装Git的注意事项如果机器上已经装过老版本Git现在想升级可以直接覆盖安装不需要先卸载。安装程序会保留原来的全局配置文件~/.gitconfig同时把可执行文件替换成新版本。我试过很多次覆盖安装后原有的用户名、邮箱、SSH密钥路径、换行符策略这些配置都还在。真正需要卸载重装的场景只有一种上一次安装过程损坏了PATH环境变量或者文件关联覆盖安装也没法修复。重装时如果再遇到奇怪问题比如安装完成后右键菜单消失了可以回头看安装过程中Select Components里的Windows Explorer integration有没有被勾选。右键菜单丢失大部分是这里的锅重装一次勾上就能解决。4. 不配好这四项Claude Code跑起来会很难受配置部分很多人当成可做可不做的环节其实大错特错。下面四个配置项前三个不配好Claude Code在执行提交类操作时会直接报错或者行为混乱第四个不配好你在拉取私有仓库时会被反复要求输密码体验感直线下降。4.1 全局用户名与邮箱Git在提交代码时每次commit记录里都会写入作者名和邮箱。不设置的话Git会用系统用户名拼一个用户名主机名作为默认作者这样生成的历史记录非常难看。而且Claude Code帮你提交代码时会去读取这个配置来决定commit的作者如果配置是乱的生成的提交记录也乱七八糟。装完Git之后第一步就设置全局用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的用户名和邮箱最好长期保持稳定因为一旦提交被推送上线再去改历史记录会非常麻烦。有人会问如果某个仓库想用不同的身份怎么办那就不要加--global在该仓库目录下单独设置。Claude Code执行commit时会从仓库级到全局级再到系统级逐层读取配置仓库目录里的配置优先级最高。4.2 默认分支名统一为main旧版本Git的默认初始分支名是master新版本安装器会问你初始分支名选什么。很多人直接下一步默认结果机器上有的仓库是master、有的是main非常混乱。建议设置一下全局默认分支名git config --global init.defaultBranch main设置完成后后续git init创建的仓库默认分支统一是main。这样做的好处是和Claude Code以及主流代码托管平台的行为保持一致减少团队协作时你怎么在master分支上开发这种低级误会。4.3 换行符CRLF/LF的策略Windows和Linux/macOS的换行符不一样Windows用回车加换行CRLFUnix系只用换行LF。Git默认策略是checkout时从LF转成CRLFcommit时再转回LF这对Windows用户最友好。但如果你参与了跨平台团队项目还是要和团队统一策略。因为一旦配置文件里的换行符规则不一致git diff可能会显示大面积假改动整个文件看起来全被改了一遍实际上只是每行末尾的换行符不一样了。如果只是自己在纯Windows环境里折腾Claude Code不跟别人协作保持默认策略就行。我见过有人图省事执行git config --global core.autocrlf false来关掉换行符转换这在纯Mac或纯Linux环境没问题但在Windows里会导致文件末尾出现大量^M符号纯属自找麻烦。除非你非常清楚自己在做什么否则保持默认。4.4 凭据管理与SSH密钥准备Git通过HTTPS方式拉取私有仓库时需要身份验证。Windows下默认启用Git Credential Manager它会弹出一个窗口让你登录登录一次后凭据被安全保存以后不再询问。这个机制对Claude Code来说非常关键因为仓库走HTTPS时Claude Code在自动拉取或推送时需要读取凭据不能每次都弹窗卡住。如果想彻底免去HTTPS的凭据流程更推荐用SSH密钥。生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱一路回车默认会在~/.ssh/目录下生成id_ed25519和id_ed25519.pub两个文件。然后把.pub文件里的公钥内容配置到代码托管平台账户的SSH Keys区域。配置完成后在克隆仓库时选择SSH地址就能实现完全免密操作。这个能力在Claude Code后面自动处理仓库时非常有用。4.5 查看现有配置避免我以为配了其实没配配置完上面几项后建议跑一条命令确认当前生效的配置来自哪里git config --list --show-origin--show-origin会显示出每个配置项的来源文件路径。这样做的好处是当系统里有多份配置文件比如系统级、全局级、仓库级同时存在时你能清楚看到哪一级的配置覆盖了哪一级。我遇到过不少情况明明在全局配置里改了用户名但某个仓库的本地配置还留着旧值导致提交时作者信息还是旧的。用这条命令一眼就能看出问题出在哪。5. 接上Claude Code之前最常见的四个报错5.1 无法将git项识别为cmdlet、函数、脚本文件或可运行程序的名称这个报错本质上只有三种原因Git没装、装了但没选对PATH选项、PATH被破坏。我帮别人排查时发现最常见的是第二种——安装时手滑选了Use Git from Git Bash only安装器就不把Git写进系统PATH。解决方式也很直接重新运行安装程序选择Modify修改把PATH选项改成Git from the command line and also from 3rd-party software等安装完成重启终端。如果不想重装也可以手动编辑环境变量Path加上C:\Program Files\Git\cmdGit装在其他盘就改成实际路径。改完之后一定要重开终端。这里有个容易踩的坑很多人在系统设置里改完环境变量后只关闭当前终端再打开发现还是不行。原因在于Windows中已经运行的进程不会自动感知环境变量变化最稳妥的做法是把所有终端窗口全部关掉重新开启一个。5.2 fatal: not a git repository (or any of the parent directories): .git这个报错的意思是当前目录不是Git仓库往上层目录找也找不到。Claude Code在设计上是面向项目目录工作的落地运行时它会尝试读取当前目录的Git信息。如果你在一个普通文件夹里直接启动它大概率就会收到这个提示。解决办法很简单在项目目录里执行git init初始化仓库或者用git clone把已有仓库拉下来之后再启动Claude Code。但有一个细节很多人没注意Claude Code识别的是最近的Git仓库环境。也就是说如果你在某个仓库的子目录里启动它它能向上识别到父级仓库。但如果你在子目录里多此一举地运行了git init那就等于在子目录里建了一个新仓库造成嵌套仓库的情况Claude Code会混淆到底该以哪个仓库为准。我的建议是始终在项目根目录初始化或启动。5.3 login failed. Check API token or GitLab version这个报错来自Git与代码托管平台比如GitLab交互时的认证失败通常出现在通过HTTPS凭据或Token访问私有仓库的场景。第一次遇到不用慌按顺序排查三个点第一Token是否过期很多平台的安全策略会定期让Token失效需要重新生成第二Token的权限范围是否包含要访问的仓库如果只勾了read权限推送时就会报login failed第三Git版本是否太老某些新版本的平台API对老版本Git不兼容升级Git到最新版往往能直接解决。如果是用SSH方式认证报错信息会以Permission denied (publickey)的形式出现那是SSH公钥没配对的问题重新检查本地~/.ssh/id_ed25519.pub是否已经正确添加到托管平台。这两种问题在Claude Code运行期间出现时它会停下来等你处理处理完重新执行命令即可不需要重启Claude Code。5.4 git clone卡住或报网络错误Claude Code在初始化项目时经常要clone远程仓库一旦clone卡住很多人就怀疑是Claude Code的Bug其实问题往往出在Git和网络的交互层面。先做一个最基础的排查单独在终端执行git clone如果单独执行也卡住那跟Claude Code没有任何关系。网络链路问题可以从几个方向逐一排查确认当前网络连接是否稳定、是否限制了对外访问尝试把远程地址从HTTPS切换成SSH或者反过来如果仓库本身很大可以考虑用--depth 1做浅克隆只拉取最新的提交记录减少传输数据量实在不行换个网络环境再试一次。在具体操作上我建议把git clone能否单独成功当成前置条件前置条件通过了再回到Claude Code里操作这样能把问题边界划得很清楚。6. macOS和Linux下装Git的快速路径6.1 macOS用Homebrew装最新版macOS系统自带一份Git但版本通常比较旧。Claude Code在mac上跑我还是建议先通过Homebrew装一份新版本brew install git装完后确认一下PATH顺序执行which git输出应该是/opt/homebrew/bin/git而不是/usr/bin/git。如果不是检查一下~/.zshrc或~/.bash_profile里的PATH变量顺序把Homebrew的路径放在前面。macOS用户还要注意首次运行git可能会触发Xcode Command Line Tools安装提示这是正常现象按提示装完即可但装完之后仍需安装Homebrew版本的Git来覆盖它。6.2 Linux按发行版选对应包管理器Linux用户对终端命令一般不会太陌生这里只把常用命令列一下发行版安装命令Debian/Ubuntusudo apt install gitCentOS/RHELsudo yum install git 或 sudo dnf install gitArch Linuxsudo pacman -S git主要的注意点是某些长期维护版本LTS的默认软件源里Git版本会偏老。比如某些Ubuntu LTS的apt源里Git还在2.25左右如果Claude Code需要更新的特性建议添加官方源或直接编译安装最新版本。不过这种情况属于少数大部分场景用发行版自带的包管理器装好就够用。无论用哪种方式装完后同样要用git --version和which git做一轮验证确认系统实际调用的版本就是预期版本。正文到这里Claude Code安装的第一块地基算是打完了。我个人在配环境时最深的体会是花十分钟把Git装好并验证完比之后反复排查一小时环境问题要划算得多。你可以按这个顺序做一次快速自检git --version确认可执行文件就位git config --global user.name和git config --global user.email确认身份配置再执行一次git clone验证认证链路。三步都过了再放心去装Claude Code本体。下一篇会接着讲Claude Code安装的下一步到时候直接在这一步的基础上继续操作就行。