如果你和我一样每天都泡在终端里那大概率已经听说了 Claude Code。简单说它是一款跑在命令行里的 AI 编程助手不用切网页、不用复制粘贴代码直接在终端里让它读项目、改文件、写测试、解释报错。这篇图文教程记录我在 Mac 上从零装好 Claude Code 的完整过程包括环境检查、安装命令、登录配置、常见报错每一步都尽量写清楚。适合第一次碰命令行的新手也适合换新 Mac 后想快速恢复环境的老手。1. 安装前的准备先确认你的 Mac 够不够格1.1 查看系统版本和芯片类型安装任何命令行工具之前我都会先确认系统环境。Claude Code 本身对硬件要求不高但你的 macOS 版本、Node.js 环境会直接决定能不能顺利跑起来。打开终端的方式有很多种最简单的是按Command 空格输入“终端”或“Terminal”回车。也可以在“访达”里找到「应用程序 - 实用工具 - 终端」。打开之后先看一行系统信息sw_vers输出大概是这样的ProductName: macOS ProductVersion: 14.5 BuildVersion: 23F79只要你的系统是 macOS 12 或更高版本基本都能跑。芯片方面Apple SiliconM1/M2/M3 系列和 Intel 芯片都没有问题。不过后续装 Node.js 时官网安装包会自动匹配芯片架构不用太担心。然后检查一下磁盘空间。Claude Code 本身只有几十 MB但 Node.js、npm 全局包以及项目依赖会占掉一些空间建议至少留出 2GB 空闲空间。命令行工具不像图形软件那样显眼但装多了也会慢慢堆积。1.2 安装 Node.js 和 npm两条路任选Claude Code 是用 Node.js 写的命令行工具所以第一步是装 Node.js。npm 是随 Node.js 一起安装的包管理器后续装 Claude Code 用的就是它。我比较推荐两种方式你自己选一种方式 A官网下载 pkg 安装包去 Node.js 官网下载 LTS长期支持版本的安装包双击安装一路下一步。这种方式对新手最友好装完打开终端验证一下node -v npm -v能看到版本号就说明装好了。缺点是以后升级 Node.js 需要手动重新下载安装包。方式 B用 Homebrew 安装如果你已经装了 Homebrew那就一条命令brew install node22Homebrew 的优点是便于统一管理brew upgrade node就能升级。没装 Homebrew 的话可以先去装 Homebrew。安装过程可能比较长耐心等它跑完。不管用哪种方式装完之后务必重新打开一个终端窗口让 PATH 环境变量生效。我遇到过好多次刚装完 Node.jsnode命令却提示找不到其实就是终端没重开。1.3 准备你的 Claude 账号Claude Code 需要一个能登录 Claude 的账号。这里分两种场景你使用的是 Claude 的订阅账号Pro/Max 这类第一次运行时用浏览器登录授权即可。如果你走 API 模式则需要提前准备好 API Key后续在终端里配置环境变量。这一步很关键我建议先把账号准备好再安装。不然装完了卡在登录环节会很难受。账号的注册和开通我就不展开说了网上的官方指引很详细按流程走就行。2. 安装 Claude Code 的完整步骤两种方式任选2.1 全局安装一劳永逸在终端里直接执行这条命令npm install -g anthropic-ai/claude-code正常情况下你会看到一堆安装日志最后出现类似这样的信息added 350 packages in 12s安装完成之后验证一下claude --version如果输出了类似1.0.x的版本号说明安装成功。这里解释一下为什么要全局安装。全局安装意味着 npm 把这个工具放到了系统的全局目录之后你不管在哪个目录下都能直接输入claude启动它。如果你有多个项目要使用全局安装是最省心的。2.2 用 npx 临时运行先体验再决定如果你只是好奇想试试看不想在全局留下东西可以用 npx 直接运行npx anthropic-ai/claude-codenpx 会临时下载这个工具并直接执行不需要提前安装。第一次运行时会多等一会儿因为要下载包之后会缓存起来。它和全局安装的区别主要有几点对比项全局安装npx 临时运行命令入口claudenpx anthropic-ai/claude-code磁盘占用常驻占用固定空间有缓存多次运行后会累积版本升级npm update -g自动使用新版本适用场景日常主力使用尝鲜、跑一次就完事我的建议是既然你准备装它直接用全局安装省事。2.3 升级和卸载别漏掉这些细节Claude Code 更新频率很高隔三差五就出新版本。升级命令很简单npm update -g anthropic-ai/claude-code或者装最新版npm install -g anthropic-ai/claude-codelatest升级之后最好执行claude --version确认一下有时候新版本会调整配置项老配置可能不兼容。卸载同样是一条命令npm uninstall -g anthropic-ai/claude-code但要注意卸载程序不会删除你本地的配置文件比如~/.claude.json和~/.claude/目录。如果你确定以后不再用想清理干净需要手动删除这些文件rm -rf ~/.claude.json ~/.claude删除前想清楚这会把你的登录状态和自定义设置一起清掉。3. 初始化配置登录和权限比安装更容易翻车3.1 首次启动与登录认证安装完成之后在项目目录里输入claude第一次启动会看到欢迎界面并提示登录。通常有两种方式OAuth 登录终端里会显示一个链接和授权码同时自动打开浏览器。你在浏览器里完成授权然后回到终端继续。这个流程体验最好不用手填大段 Key。API Key 登录如果选择这个你需要把 API Key 粘贴到终端里回车确认。终端里的提示大概长这样✔ Please log in to Claude Enter the code shown in your browser授权成功后终端会显示当前账号的信息然后进入一个以/开头的交互界面等待你输入问题。这里我提醒一句如果你的终端没有自动打开浏览器手动把链接复制到浏览器里访问就行。别傻等有几次我就是卡在这一步。3.2 配置文件与环境变量登录完成之后Claude Code 会在你的用户目录下生成配置文件。比较常见的有~/.claude.json保存会话、登录信息等全局数据。~/.claude/settings.json保存项目的权限和偏好设置。如果你走 API Key 路线还可以通过环境变量来配置。在~/.zshrc如果你用 zsh里加一行export ANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxxxxx然后执行source ~/.zshrc让配置生效。使用环境变量最大的好处是多个项目共用一个 Key不用每个项目单独设置。但代价是 Key 会裸露在你的 shell 配置文件里。我建议不要把 Key 提交到 Git 仓库更不要截图发到群里。凡是存过 Key 的文件我都习惯性地检查一下权限避免被别人看到。3.3 macOS 权限设置别嫌麻烦macOS 对终端访问文件和辅助功能卡得很严。首次运行 Claude Code 的时候系统可能会弹窗询问是否允许终端访问“文件夹中的文件”或者“控制其他进程”。这里不要盲点“不允许”。如果选了不允许后续它可能读不到你的项目文件或者无法帮你自动修改代码。我实际的经历是第一次启动时弹窗没注意直接点了不允许结果 Claude Code 连当前目录都看不到报了一堆权限错误。后来我打开「系统设置 - 隐私与安全性 - 辅助功能」把终端添加进去再重新启动 Claude Code 才好。辅助功能权限主要用于模拟键盘输入和点击操作如果你只让它读代码、回答问题不一定要开。但如果你的工作流涉及自动编辑文件建议还是把权限给足。权限设置界面的路径大体是系统设置 隐私与安全性 辅助功能。不同 macOS 版本可能略有差异但关键字都是“辅助功能”。4. 上手实战在项目里让它帮你干活4.1 进入项目目录并启动登录完成后我们就可以正式使用了。假设你有一个项目~/work/demo-project先进入这个目录cd ~/work/demo-project claude启动之后终端会变成一个对话界面就像跟一个同事聊天。你可以直接输入自然语言比如你好请先介绍一下这个项目的整体结构和核心功能。Claude Code 会调用工具读取项目目录、查看关键文件然后给你一个概括性的回复。这一步看起来简单但它实际做了很多事情它会列出目录树、读取 package.json、README 等文件然后组织语言回答。我在第一次用的时候最大的感受是它真的在“读”项目而不是瞎猜。它会执行命令也会读取文件内容最终输出带上下文理解的回答。4.2 常用斜杠命令先记这几个Claude Code 的交互式界面里有很多以/开头的命令。我平时最常用的有这几个/init让 Claude Code 扫描项目生成项目说明文件用于后续对话的上下文初始化。/compact当对话太长、上下文接近上限时压缩历史消息保留关键信息。/clear清空当前会话重新开始。/help查看所有可用命令和快捷键。我建议你每次开始新项目时先执行/init让它了解项目背景。否则它可能不知道你有没有测试框架、用的什么包管理器回答就会比较泛。执行/init之后它会在项目目录里生成类似CLAUDE.md的文件后续每次启动都会自动读取。如果你前期和它聊了很多无关内容把上下文塞满了可以执行/clear重新开始不用重启终端。这比退出重进快得多。4.3 让它改代码、写测试真正让它干活的时候建议你提需求时带点上下文。比如请帮我修改 src/utils.ts 里的 formatDate 函数让它支持时区参数。它会先读取这个文件找到对应函数然后展示修改后的代码片段。默认情况下修改文件之前会请求你的确认。你在终端里选同意它才会真正写入文件。写测试也是一样的。它可以在项目里找出测试框架然后生成对应的测试文件。我第一次试的时候让它给一个工具函数写测试它直接创建了测试文件并运行了测试命令失败了还会自己改。这里有个小建议在你对代码不熟悉的时候可以先用git做好版本控制。这样就算它改错了你也能一键回滚。我自己就吃过亏让它批量重命名结果改漏了一个文件幸好有 Git 才恢复过来。5. 常见报错与排查技巧实录5.1 claude: command not found明明安装成功了输入claude却提示找不到命令。这个问题的根源在于 npm 的全局 bin 目录不在 PATH 里。排查思路是先看 npm 全局前缀是什么npm config get prefix如果输出的是/usr/local那你需要检查/usr/local/bin是否在 PATH 里。更稳妥的办法是把全局目录设置到用户目录下npm config set prefix ~/.npm-global export PATH$PATH:~/.npm-global/bin然后重新打开终端再试claude --version。改成用户目录之后权限问题也顺手解决了后面讲到的 EACCES 错误会少很多。5.2 安装时 EACCES 权限错误如果你在安装时看到类似EACCES: permission denied的报错说明 npm 没有权限往系统目录里写文件。最直接的办法是别用sudo npm install -g因为 sudo 装出来的全局包容易产生权限混乱。推荐做法就是上面提过的把 npm 全局前缀改到用户目录npm config set prefix ~/.npm-global之后安装就不需要 sudo 了。如果你以前用 sudo 装过一些包新配置的全局目录可能读取不到旧包重新安装一遍即可。另一个排查点是检查~/.npm-global目录是否存在不存在就手动创建mkdir -p ~/.npm-global5.3 网络超时、下载失败安装过程中最常见的问题就是网络超时。npm 默认源在国外网络波动时下载会失败或非常慢。表现通常是npm ERR! network request to https://registry.npmjs.org/... failed遇到这种情况可以切换 npm 镜像源。我个人是在国内网络环境下把默认源换成了国内镜像源npm config set registry https://registry.npmmirror.com设置完之后重新执行安装命令速度会明显变快。如果你不想永久修改可以只在安装时指定npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com镜像源只影响 npm 下载包的过程不影响 Claude Code 登录和对话。不过它运行时如需访问外部接口仍然要求你的网络能连通对方服务。遇到登录或连接超时优先检查网络状态不要急着认为工具坏了。5.4 登录失败、认证失效有时候你在浏览器里完成了授权回到终端却发现提示认证失败或者第二天再启动发现需要重新登录。这种情况一般出现在认证令牌过期或本地 token 损坏。先不要急着卸载重装。我试过的有效办法是检查系统时间是否正确。时间不对会导致证书校验失败登录就容易出问题。删除本地旧的登录配置后重新登录rm -rf ~/.claude.json ~/.claude/重新运行claude按照提示完成授权。需要注意的是删除配置会同时清掉你之前的所有本地设置和会话记录。如果里面有重要的对话上下文建议先确认不需要了再删。还有一种情况是 API Key 失效。如果你用的是 API Key检查环境变量是否加载正确echo $ANTHROPIC_API_KEY如果输出为空或明显不对重新export一下并确认你复制的时候没有多余空格。写在最后这段时间用下来我最深的体会是Claude Code 的安装其实不难难的往往是环境细节和权限处理。只要记住几个关键点——Node.js 版本别太老、npm 全局目录改成用户目录、macOS 辅助功能权限给足——整个流程十分钟内肯定能搞定。另外这个工具迭代很快建议隔一两周就claude --version看一下版本顺手npm update -g anthropic-ai/claude-code升级一下。新版经常会修复一些奇怪的 bug也能少踩坑。希望这篇记录能帮你顺利用起来。