1. 为什么要在 Mac 上折腾 Claude Code
Mac 用户对命令行工具的执念，大概和机械键盘爱好者对轴体的挑剔差不多——一旦习惯了终端里那种“敲一行命令，世界就安静地开始干活”的节奏，就很难再回到鼠标点来点去的操作方式。Claude Code 正是这样一个把 AI 编程能力直接塞进终端的工具，它由 Anthropic 推出，定位是“住在你终端里的编程搭子”。你不需要打开浏览器、不需要复制粘贴代码到对话框，直接在项目目录里敲一句自然语言，它就能读你的文件、改你的代码、跑你的测试。
这个教程面向的是所有想在 Mac 上把 Claude Code 跑起来的人，不管你是刚买 Mac 没多久的新手，还是已经用 Homebrew 装过几十个包的老玩家。我会从环境准备讲起，把 Node.js 安装、npm 全局配置、Claude Code 安装、API 认证、VS Code 集成、常见报错排查这一整条链路全部走一遍。中间会穿插大量我在实际安装过程中踩过的坑，比如 Homebrew 报错、unable to connect to anthropic services这类连接问题、权限配置、路径冲突等等。
先说清楚一件事：Claude Code 不是一个图形界面软件，它没有图标、没有窗口，安装完之后你只能在终端里通过claude命令来调用它。这一点和 Cursor、VS Code 里的 AI 插件完全不同。它的优势在于轻量、快速、和你的项目文件系统直接交互，不需要来回切换窗口。缺点也很明显——如果你对命令行完全陌生，前期会有一段适应期。不过别担心，这篇教程会把每一步都拆到你能照着敲的程度。
在正式开始之前，你需要确认几件事：你的 Mac 系统版本最好是 macOS 12 及以上，芯片是 Apple Silicon（M 系列）或 Intel 都可以，但 Apple Silicon 在性能上会更有优势。另外，你需要一个 Anthropic 的账号，并且能够正常访问 Anthropic 的 API 服务。这是整个安装过程中最关键的前置条件，后面我会详细讲怎么配置。
2. 安装前的环境准备与工具选型
2.1 检查 Mac 系统基础环境
在动手安装任何东西之前，先花两分钟确认一下你的系统状态。打开终端（Terminal），你可以通过 Spotlight 搜索“终端”或者到“应用程序 > 实用工具”里找到它。打开之后，依次执行下面几条命令，看看输出结果。
# 查看系统版本 sw_vers # 查看芯片架构 uname -m # 查看当前 shell echo $SHELLsw_vers会输出 macOS 的版本号，比如ProductVersion: 14.5。uname -m在 Apple Silicon 机器上会显示arm64，Intel 机器上显示x86_64。echo $SHELL一般会显示/bin/zsh，这是 macOS 从 Catalina 开始默认的 shell。如果你看到的是/bin/bash，说明你的默认 shell 还是旧版的 bash，后面配置环境变量的时候需要注意路径文件的不同。
为什么要先查这些？因为 Claude Code 依赖 Node.js 运行环境，而 Node.js 在不同芯片架构上的安装方式略有差异。Apple Silicon 原生支持 arm64 架构的 Node.js，性能更好；如果你不小心装了 x86_64 版本的 Node.js，虽然能跑，但会通过 Rosetta 转译，速度会打折扣。另外，macOS 版本太低可能会导致某些依赖包无法正常编译，所以提前确认可以避免后面走弯路。
还有一个容易被忽略的点：检查你的磁盘剩余空间。Node.js 加上 npm 全局包，再加上 Claude Code 本身，大概会占用 500MB 到 1GB 左右的空间。如果你的 Mac 存储空间已经告急，建议先清理一下。说到清理，很多 Mac 用户会搜“mac系统数据怎么清理”，其实最直接的办法是打开“关于本机 > 存储空间”，看看“系统数据”那一栏是不是异常膨胀。如果是，可以用一些清理工具或者手动删除缓存文件，但这不是本教程的重点，你只需要确保有足够的空间就行。
2.2 Homebrew 安装与常见报错处理
Homebrew 是 macOS 上最流行的包管理器，虽然 Claude Code 不一定要通过 Homebrew 安装，但后续很多开发工具（比如 Git、Node.js）用 Homebrew 管理会方便很多。如果你已经装过 Homebrew，可以跳过这一节，但建议还是看一眼版本是否最新。
安装 Homebrew 的命令官方给得很简单：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"但实际操作中，很多人会卡在这一步。最常见的报错是网络连接超时，因为 Homebrew 的安装脚本需要从 GitHub 拉取文件。如果你遇到curl: (7) Failed to connect或者类似的网络错误，可以尝试多试几次，或者检查你的网络环境是否稳定。
另一个高频报错是权限问题。比如你看到Permission denied或者EACCES之类的提示，这通常是因为之前用sudo安装过 Homebrew，导致目录权限混乱。解决办法是修复目录权限：
sudo chown -R $(whoami) /usr/local/Homebrew sudo chown -R $(whoami) /opt/homebrew注意，Apple Silicon 机器的 Homebrew 默认安装在/opt/homebrew，Intel 机器在/usr/local/Homebrew。你需要根据你的芯片类型选择对应的路径。
安装完成后，还需要把 Homebrew 添加到环境变量里。对于 Apple Silicon 机器，执行：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc对于 Intel 机器：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc验证安装是否成功：
brew --version如果输出了版本号，比如Homebrew 4.x.x，说明安装成功。这里有个实操心得：如果你在安装 Homebrew 时反复失败，不要死磕，可以先跳过 Homebrew，直接用 Node.js 官方安装包来装 Node.js。Claude Code 的核心依赖只是 Node.js 和 npm，Homebrew 只是让管理更方便而已。
2.3 Node.js 安装的三种方案对比
Node.js 是 Claude Code 的运行基础，没有它，后面的一切都无从谈起。在 Mac 上安装 Node.js 有三种主流方式，我分别说一下优缺点，你可以根据自己的情况选择。
第一种是用 Homebrew 安装，命令是brew install node。这是最省事的方式，Homebrew 会自动处理依赖和路径配置。缺点是版本更新可能稍微滞后，而且如果你同时需要多个 Node.js 版本，Homebrew 不太方便切换。
第二种是用 Node.js 官方安装包。到 Node.js 官网下载 macOS 的.pkg安装包，双击安装即可。这种方式适合完全不想碰命令行的用户，但后续升级需要手动下载新版本。
第三种是用 nvm（Node Version Manager）来管理。这是我最推荐的方式，尤其是你以后可能需要在不同项目之间切换 Node.js 版本。安装 nvm 的命令是：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后，需要把 nvm 加载到 shell 配置里：
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc source ~/.zshrc然后用 nvm 安装 Node.js 的 LTS 版本：
nvm install --lts nvm use --lts验证安装：
node --version npm --version如果输出了版本号，比如v20.x.x和10.x.x，说明 Node.js 和 npm 都装好了。这里要注意，Claude Code 对 Node.js 版本有最低要求，建议使用 Node.js 18 及以上版本。如果你用的是很老的版本，可能会遇到兼容性问题。
3. Claude Code 安装与认证配置
3.1 通过 npm 全局安装 Claude Code
Node.js 环境准备好之后，安装 Claude Code 本身其实只有一条命令：
npm install -g @anthropic-ai/claude-code这条命令会从 npm 仓库下载 Claude Code 的最新版本，并安装到全局路径下。安装完成后，你可以用下面的命令验证：
claude --version如果输出了版本号，比如2.1.272，说明安装成功。如果提示command not found: claude，说明 npm 的全局路径没有加到你的 PATH 环境变量里。这是新手最容易遇到的问题之一。
解决办法是找到 npm 的全局安装路径：
npm config get prefix这个命令会输出一个路径，比如/usr/local或者/opt/homebrew。然后确认这个路径下的bin目录是否在 PATH 里：
echo $PATH如果没有，你需要手动添加。对于 zsh 用户，编辑~/.zshrc文件，加入：
export PATH="$(npm config get prefix)/bin:$PATH"然后执行source ~/.zshrc让配置生效。再次运行claude --version，应该就能看到版本号了。
这里有一个实操心得：如果你之前用sudo npm install -g安装过其他包，可能会导致全局目录的权限问题。表现为安装 Claude Code 时出现EACCES错误。解决办法是重新配置 npm 的全局目录到用户目录下：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc source ~/.zshrc然后重新执行安装命令。这样做的好处是不需要sudo，避免了权限混乱的问题。
3.2 Anthropic API 认证与连接配置
Claude Code 安装好之后，第一次运行claude命令时，它会引导你进行认证。认证方式主要有两种：一种是通过 Anthropic 账号的 OAuth 登录，另一种是配置 API Key。
如果你选择 OAuth 登录，终端会输出一个链接，你需要在浏览器里打开这个链接，登录你的 Anthropic 账号，然后授权。授权完成后，浏览器会显示一个验证码，你把它复制回终端即可。这个过程和很多 CLI 工具的登录流程类似，不算复杂。
如果你选择 API Key 方式，需要先到 Anthropic 的控制台创建一个 API Key。然后通过环境变量配置：
export ANTHROPIC_API_KEY="你的API Key"为了让这个环境变量在每次打开终端时都生效，建议把它写到~/.zshrc文件里：
echo 'export ANTHROPIC_API_KEY="你的API Key"' >> ~/.zshrc source ~/.zshrc配置完成后，运行claude命令，如果能看到 Claude Code 的欢迎界面，说明认证成功。
但是，很多人在这一步会遇到unable to connect to anthropic services或者failed to connect to api.anthropic.com这样的报错。这个问题的原因通常有三种：一是网络连接不稳定，二是 API Key 配置错误，三是 Anthropic 服务本身出现了临时故障。
排查思路是这样的：首先确认你的网络能正常访问 Anthropic 的 API 地址，可以用curl测试：
curl -I https://api.anthropic.com如果返回了 HTTP 状态码（比如 200 或 401），说明网络是通的。如果直接超时或者报错，说明网络层面有问题。其次检查 API Key 是否正确，注意不要有多余的空格或换行。最后，如果前两项都没问题，可能是 Anthropic 服务端的临时问题，等一段时间再试。
注意：API Key 是非常敏感的信息，不要把它提交到 Git 仓库里，也不要在公开场合分享。如果你怀疑 Key 泄露了，立即到 Anthropic 控制台撤销并重新生成。
3.3 VS Code 集成与终端配置
Claude Code 虽然是一个命令行工具，但它可以和 VS Code 配合使用，提升开发体验。具体来说，你可以在 VS Code 的集成终端里直接运行claude命令，这样就不用来回切换窗口了。
配置方法很简单：打开 VS Code，按下Cmd + J打开集成终端，然后直接输入claude即可。如果你希望 VS Code 启动时自动打开终端，可以在设置里搜索terminal.integrated.automationProfile进行配置。
另外，Claude Code 支持在项目目录下创建一个CLAUDE.md文件，用来告诉 Claude 你的项目结构、编码规范、常用命令等信息。这个文件相当于给 Claude 的一份“项目说明书”，能显著提升它对你项目的理解准确度。比如你可以这样写：
# 项目说明 这是一个基于 React + TypeScript 的前端项目。 ## 常用命令 - 开发：npm run dev - 构建：npm run build - 测试：npm run test ## 编码规范 - 使用函数式组件 - 使用 ESLint + Prettier - 组件文件使用 PascalCase 命名有了这个文件，Claude Code 在执行任务时会更贴合你的项目习惯，减少“答非所问”的情况。
4. 实操全流程与关键环节记录
4.1 从零开始的完整安装流程
假设你是一台全新的 Mac，什么都没装过，下面是从零开始的完整流程。我会把每一步的命令和预期输出都写清楚，你可以直接照着敲。
第一步，打开终端，检查系统版本和芯片架构：
sw_vers uname -m确认系统是 macOS 12 以上，芯片是 arm64 或 x86_64。
第二步，安装 Homebrew（如果还没装）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装完成后，按照终端提示把 Homebrew 加到 PATH 里。Apple Silicon 机器执行：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc第三步，用 Homebrew 安装 nvm：
brew install nvm然后创建 nvm 的工作目录：
mkdir ~/.nvm把 nvm 加载配置写到~/.zshrc：
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc source ~/.zshrc第四步，用 nvm 安装 Node.js LTS 版本：
nvm install --lts nvm use --lts nvm alias default lts/*验证：
node --version npm --version第五步，安装 Claude Code：
npm install -g @anthropic-ai/claude-code第六步，验证安装：
claude --version第七步，配置 API Key：
echo 'export ANTHROPIC_API_KEY="你的API Key"' >> ~/.zshrc source ~/.zshrc第八步，运行 Claude Code：
claude如果一切顺利，你会看到 Claude Code 的欢迎界面，可以开始输入自然语言指令了。
4.2 参数配置与性能调优
Claude Code 提供了一些配置选项，可以通过claude config命令来管理。比如你可以设置默认的模型、调整输出格式、配置代理等。下面是一些常用的配置项。
设置默认模型：
claude config set -g model claude-sonnet-4-20250514这个命令会把全局默认模型设置为 Claude Sonnet 4。如果你有特定的模型偏好，可以在这里指定。
查看当前配置：
claude config list这个命令会列出所有配置项及其当前值，方便你确认配置是否正确。
如果你觉得 Claude Code 的响应速度不够快，可以尝试调整一些参数。比如减少上下文窗口的大小，或者关闭一些不必要的功能。不过要注意，这些调整可能会影响输出质量，需要根据实际情况权衡。
另外，Claude Code 支持在项目目录下创建.claude/settings.json文件，用来配置项目级别的设置。比如：
{ "model": "claude-sonnet-4-20250514", "maxTokens": 4096, "temperature": 0.7 }这个文件会覆盖全局配置，只对当前项目生效。适合在不同项目之间使用不同的配置。
4.3 实际使用场景演示
安装配置完成之后，Claude Code 到底能干什么？我举几个实际的使用场景，你可以感受一下它的工作方式。
场景一：代码审查。进入你的项目目录，运行claude，然后输入“帮我审查一下 src/utils 目录下的代码，看看有没有潜在的问题”。Claude Code 会读取这些文件，分析代码逻辑，指出可能存在的 bug、性能问题或者不规范的地方。
场景二：自动修复。如果你有一个测试一直跑不过，可以输入“运行 npm test，然后帮我修复失败的测试”。Claude Code 会执行测试命令，读取错误输出，然后尝试修改代码来修复问题。整个过程不需要你手动复制粘贴错误信息。
场景三：代码生成。输入“帮我写一个 React 组件，实现一个带搜索功能的用户列表，使用 TypeScript 和 Tailwind CSS”。Claude Code 会根据你的项目结构和技术栈，生成符合规范的代码文件。
场景四：文档生成。输入“为 src/api 目录下的所有接口生成 API 文档，使用 Markdown 格式”。Claude Code 会读取接口定义，生成结构化的文档。
这些场景的共同点是：你只需要用自然语言描述需求，Claude Code 会自己决定读哪些文件、执行哪些命令、生成什么内容。这种交互方式和传统的代码补全工具完全不同，更像是你在指挥一个初级开发者干活。
5. 常见报错与排查技巧实录
5.1 安装阶段高频问题速查
在安装 Claude Code 的过程中，有几个报错出现的频率特别高。我把它们整理成了一张表，方便你快速定位问题。
| 报错信息 | 可能原因 | 解决方法 |
|---|---|---|
command not found: claude | npm 全局路径未加入 PATH | 执行npm config get prefix，把输出的路径下的 bin 目录加入 PATH |
EACCES: permission denied | npm 全局目录权限问题 | 重新配置 npm prefix 到用户目录，避免使用 sudo |
unable to connect to anthropic services | 网络问题或 API Key 错误 | 检查网络连接，确认 API Key 正确，重试 |
failed to connect to api.anthropic.com | DNS 解析或网络不通 | 用curl -I https://api.anthropic.com测试连通性 |
doesn't look like an anthropic model | 模型名称配置错误 | 检查claude config中的模型名称是否正确 |
npm ERR! code ENOVERSIONS | Node.js 版本过低 | 升级到 Node.js 18 或以上 |
zsh: command not found: brew | Homebrew 未加入 PATH | 执行 Homebrew 的 shellenv 配置命令 |
这张表基本覆盖了 90% 的安装问题。如果你遇到的报错不在表里，可以先把完整的报错信息复制下来，到搜索引擎里搜一下，通常能找到相关的讨论。
5.2 连接类问题的深度排查
unable to connect to anthropic services这个报错值得单独拿出来讲，因为它出现的频率最高，而且原因最复杂。我把它拆成几个排查步骤，你可以按顺序检查。
第一步，确认网络连通性。在终端执行：
curl -v https://api.anthropic.com如果看到Connected to api.anthropic.com并且有 HTTP 响应，说明网络是通的。如果卡在Trying xxx.xxx.xxx.xxx...或者直接超时，说明网络层面有问题。
第二步，检查 DNS 解析。执行：
nslookup api.anthropic.com如果解析不出 IP 地址，说明 DNS 有问题。可以尝试更换 DNS 服务器，比如改成8.8.8.8或1.1.1.1。
第三步，检查 API Key。执行：
echo $ANTHROPIC_API_KEY确认输出的 Key 是正确的，没有多余的空格或换行。如果 Key 是空的，说明环境变量没有生效，需要重新配置。
第四步，检查系统时间。Anthropic 的 API 会验证请求的时间戳，如果你的系统时间偏差太大，可能会导致认证失败。执行：
date确认时间是正确的。如果不对，到“系统设置 > 通用 > 日期与时间”里开启自动设置。
第五步，如果以上都没问题，可能是 Anthropic 服务端的临时故障。可以到 Anthropic 的状态页面查看服务状态，或者等一段时间再试。
提示：如果你在公司网络或校园网环境下使用，可能会遇到防火墙限制。这种情况下，可以尝试切换到其他网络环境测试。
5.3 权限与路径冲突的处理经验
Mac 系统对权限管理比较严格，尤其是在涉及系统目录的时候。我在安装过程中遇到过几次权限相关的问题，这里分享一下处理经验。
最常见的是 npm 全局安装时的EACCES错误。这个错误的根源是 npm 的全局目录（通常是/usr/local/lib/node_modules）属于 root 用户，普通用户没有写入权限。很多人第一反应是用sudo来解决，但这会带来更大的隐患——用sudo安装的包，后续升级和卸载都会遇到权限问题。
正确的做法是把 npm 的全局目录改到用户目录下。具体操作前面已经讲过，核心就是npm config set prefix '~/.npm-global'，然后把~/.npm-global/bin加入 PATH。这样做的好处是所有全局包都安装在你的用户目录下，不需要sudo，也不会污染系统目录。
另一个容易踩的坑是多个 Node.js 版本共存导致的路径冲突。如果你同时用 Homebrew 和 nvm 安装了 Node.js，可能会出现which node指向的版本和你预期不一致的情况。解决办法是统一用一个版本管理器，推荐 nvm。如果已经装了 Homebrew 版本的 Node.js，可以先卸载：
brew uninstall node然后再用 nvm 重新安装。这样可以避免路径混乱。
6. 进阶配置与效率提升技巧
6.1 自定义命令与快捷操作
Claude Code 支持自定义命令，你可以把常用的提示词保存成快捷命令，减少重复输入。具体做法是在~/.claude/commands目录下创建 Markdown 文件，文件名就是命令名。
比如创建一个review.md：
请审查当前项目的代码，重点关注： 1. 潜在的 bug 和逻辑错误 2. 性能瓶颈 3. 代码规范问题 4. 安全隐患保存之后，在 Claude Code 里输入/review，就会自动执行这个提示词。这个功能特别适合团队协作，可以把常用的代码审查、文档生成、测试编写等任务标准化。
另一个提升效率的技巧是使用--print参数进行非交互式调用。比如：
claude --print "解释一下 src/index.ts 的作用"这个命令会直接输出结果，不会进入交互模式。适合在脚本里调用，或者快速获取某个问题的答案。
6.2 项目级配置的最佳实践
对于长期维护的项目，建议在项目根目录下创建.claude目录，里面放一些项目级的配置文件。除了前面提到的settings.json，还可以放CLAUDE.md和自定义命令。
CLAUDE.md的内容应该包括：项目概述、技术栈、目录结构、常用命令、编码规范、注意事项。写得越详细，Claude Code 的表现就越好。我一般会把这个文件当作项目文档的一部分来维护，新成员加入时也可以参考。
.claude/settings.json用来配置项目级别的模型参数。比如对于需要高准确率的项目，可以把 temperature 调低；对于创意类任务，可以调高。这个文件应该提交到 Git 仓库，让团队成员共享同一套配置。
还有一个实用技巧：在.claude目录下创建ignore文件，列出不需要 Claude Code 读取的文件或目录。比如node_modules、dist、.env等。这样可以减少上下文窗口的占用，提升响应速度。
node_modules/ dist/ build/ .env *.log6.3 与其他开发工具的协同
Claude Code 可以和很多开发工具配合使用，形成一套完整的工作流。比如和 Git 配合，可以在提交代码前让 Claude Code 审查变更：
git diff --staged | claude --print "审查这些变更，指出潜在问题"和 VS Code 配合，可以在集成终端里直接调用，不需要切换窗口。和 tmux 配合，可以在一个终端窗口里同时运行多个 Claude Code 会话，分别处理不同的任务。
如果你使用 Cursor 或者 VS Code 的 AI 插件，Claude Code 可以作为补充工具。比如用 Cursor 做日常的代码补全，用 Claude Code 做复杂的重构和调试任务。两者并不冲突，反而能覆盖不同的使用场景。
另外，Claude Code 支持 MCP（Model Context Protocol）协议，可以连接外部工具和数据源。比如你可以配置它连接数据库、API 文档、内部知识库等。这个功能比较进阶，适合有定制化需求的团队。配置方式是在~/.claude/mcp.json里定义服务器信息，具体可以参考 Anthropic 的官方文档。
7. 卸载与版本管理
7.1 干净卸载 Claude Code
如果你需要卸载 Claude Code，或者想重新安装一个干净的版本，可以按下面的步骤操作。
首先卸载 npm 全局包：
npm uninstall -g @anthropic-ai/claude-code然后删除配置文件和缓存：
rm -rf ~/.claude rm -rf ~/.config/claude最后检查一下 PATH 里是否还有残留的配置。打开~/.zshrc，删除和 Claude Code 相关的行。如果你之前配置了ANTHROPIC_API_KEY环境变量，也一并删除。
验证卸载是否干净：
which claude如果没有任何输出，说明卸载完成。
7.2 版本升级与回滚
Claude Code 的更新频率比较高，新版本会带来新功能和 bug 修复。升级到最新版本：
npm update -g @anthropic-ai/claude-code查看当前版本：
claude --version如果你需要安装特定版本，可以指定版本号：
npm install -g @anthropic-ai/claude-code@2.1.272如果新版本出现了问题，想回滚到旧版本，也是用同样的命令指定旧版本号即可。建议在升级之前记录一下当前版本号，方便出问题时快速回滚。
提示：如果你在生产环境中使用 Claude Code，建议先在一个测试项目里验证新版本，确认没有问题后再全面升级。
7.3 多版本共存的方案
有些情况下，你可能需要同时保留多个版本的 Claude Code。比如一个项目依赖旧版本的行为，另一个项目想用新功能。这种情况下，可以用 nvm 来管理不同的 Node.js 环境，每个环境里安装不同版本的 Claude Code。
具体做法是创建两个 nvm 环境：
nvm install 18 --lts nvm install 20 --lts然后在不同的环境里安装不同版本的 Claude Code：
nvm use 18 npm install -g @anthropic-ai/claude-code@2.0.0 nvm use 20 npm install -g @anthropic-ai/claude-code@latest切换环境时，用nvm use 18或nvm use 20即可。这样每个环境里的 Claude Code 版本是独立的，互不影响。这个方案稍微有点折腾，适合有明确版本管理需求的用户。
8. 我的实操心得与避坑建议
折腾 Claude Code 的安装和配置，前前后后花了我大概一个下午的时间，其中大部分时间都耗在排查网络连接和权限问题上。这里分享几条我觉得最有价值的经验，希望能帮你少走弯路。
第一条，不要用sudo安装 npm 全局包。这是我在早期踩过的最大的坑。用sudo安装之后，后续的升级、卸载、配置都会遇到权限问题，而且很难彻底清理干净。正确的做法是把 npm 的全局目录配置到用户目录下，虽然多了一步配置，但后续省心很多。
第二条，API Key 的管理要规范。不要把 Key 硬编码在代码里，也不要在终端里直接export之后就忘了。最好的做法是写到~/.zshrc或者单独的配置文件里，并且确保这个文件不会被提交到 Git 仓库。如果你在团队里共享配置，可以用环境变量或者密钥管理工具。
第三条，网络问题要有耐心。unable to connect to anthropic services这个报错可能由多种原因引起，排查的时候要按顺序来：先确认网络连通性，再检查 DNS，然后检查 API Key，最后检查系统时间。不要一上来就怀疑是工具本身的问题，大部分情况下都是环境配置的问题。
第四条，善用CLAUDE.md文件。这个文件对 Claude Code 的表现影响很大。我一开始没有写这个文件，Claude Code 经常生成不符合项目规范的代码。后来花时间写了一份详细的项目说明，效果立竿见影。建议每个项目都配一个，内容不用很长，但关键信息要写清楚。
第五条，保持 Node.js 和 Claude Code 的版本更新。Anthropic 的更新频率很高，新版本通常会修复一些已知问题，提升稳定性。但也不要盲目追新，建议在测试环境验证后再升级生产环境。
最后再分享一个小技巧：如果你在终端里经常需要切换不同的项目目录，可以给 Claude Code 配置一个 alias，比如：
alias cc='claude'这样每次只需要敲cc就能启动，省几个字符。虽然看起来是小事，但日积月累能省不少时间。另外，如果你经常需要查看 Claude Code 的日志，可以用claude --debug启动，会输出详细的调试信息，排查问题时很有用。
