Claude Code Mac 使用指南

1. 概述

1.1 什么是 Claude Code

Claude Code 是 Anthropic 公司开发的官方命令行工具（CLI），它将 Claude AI 的强大能力直接集成到你的终端中。通过 Claude Code，你可以在命令行环境下与 Claude 进行交互，完成代码编写、问题解答、文件处理等各种任务。

[!info] Claude Code 的核心价值
Claude Code 不仅仅是一个聊天工具，它能够：
直接操作文件系统：读取、创建、编辑项目中的文件
执行 Shell 命令：运行构建、测试、部署等命令
理解项目上下文：分析整个代码库，提供精准的建议
多模态支持：处理图片、PDF 等多种格式的文件

1.2 适用场景

场景	说明
代码开发	编写新功能、重构代码、添加注释
Bug 修复	分析错误日志、定位问题、提供修复方案
代码审查	审查代码质量、安全性、性能问题
文档编写	生成 API 文档、README、技术文档
学习辅助	解释代码逻辑、回答技术问题

1.3 系统要求

在开始安装之前，请确保你的 Mac 满足以下要求：

要求项	最低要求	推荐配置
macOS 版本	macOS 10.15 (Catalina)	macOS 12 (Monterey) 或更高
Node.js 版本	18.0.0	20.x LTS 或 22.x
磁盘空间	500 MB	1 GB
网络	能访问 npm 仓库	稳定的网络连接

1.4 安装流程概览

[!tip] 安装流程可视化
下图展示了 Claude Code 的完整安装流程，共分为四个主要阶段。

上图展示了从零开始到成功使用 Claude Code 的完整路径。首先需要安装 Node.js 运行环境，这是 Claude Code 的运行基础。安装 Node.js 有三种方式可选：Homebrew（推荐）、nvm（适合需要管理多版本的开发者）、官网下载（最简单但不便于版本管理）。安装完 Node.js 后，通过 npm 安装 Claude Code，然后配置必要的环境变量，最后验证安装是否成功即可开始使用。

2. 安装 Node.js 环境

2.1 什么是 Node.js

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境。简单来说，它让 JavaScript 代码能够在浏览器之外运行——比如在你的电脑终端里。

[!note] 为什么 Claude Code 需要 Node.js
Claude Code 是使用 JavaScript/TypeScript 编写的命令行工具，它需要 Node.js 来执行。就像 Python 程序需要 Python 解释器一样，Claude Code 需要 Node.js 运行环境。
同时，Node.js 自带的 npm（Node Package Manager）包管理器用于安装和管理 Claude Code。

2.2 安装方式对比

macOS 上安装 Node.js 有多种方式，下面是各方式的对比：

安装方式	优点	缺点	适合人群
Homebrew	安装简单、更新方便、macOS 生态友好	需要先安装 Homebrew	大多数 Mac 用户（推荐）
nvm	支持多版本切换、项目隔离	配置稍复杂	需要管理多个 Node.js 版本的开发者
官网下载	无需额外工具、图形界面安装	版本管理不便、更新麻烦	初学者、临时使用

2.3 方法一：使用 Homebrew 安装（推荐）

2.3.1 什么是 Homebrew

Homebrew 是 macOS 上最流行的包管理器，被称为"macOS 缺失的包管理器"。它能让你通过简单的命令安装、更新、卸载各种软件。

2.3.2 检查是否已安装 Homebrew

打开终端（Terminal），输入以下命令：

如果显示路径，说明已安装 Homebrew，可以跳到步骤 2.3.4。如果显示 brew not found，需要先安装 Homebrew。

2.3.3 安装 Homebrew

[!warning] 网络要求
安装 Homebrew 需要从 GitHub 下载文件，请确保网络能够访问 GitHub。如果网络不稳定，可能需要配置代理或使用国内镜像源。

在终端中执行以下命令：

命令参数解释：

参数	含义
`-f`	`--fail`，当 HTTP 请求失败时静默失败（不显示错误页面内容）
`-s`	`--silent`，静默模式，不显示进度条
`-S`	`--show-error`，与 `-s` 配合使用时，出错时显示错误信息
`-L`	`--location`，自动跟随重定向

安装完成后，根据终端提示执行配置命令（Apple Silicon Mac 需要额外配置）：

2.3.4 使用 Homebrew 安装 Node.js

[!tip] 安装特定版本的 Node.js
如果需要安装特定版本的 Node.js，可以使用以下命令：

2.4 方法二：使用 nvm 安装（多版本管理）

2.4.1 什么是 nvm

nvm（Node Version Manager）是 Node.js 的版本管理工具，它允许你在同一台电脑上安装和切换多个 Node.js 版本。这对于需要在不同项目中使用不同 Node.js 版本的开发者非常有用。

[!info] nvm 的优势
多版本共存：可以同时安装 Node.js 16、18、20、22 等多个版本
快速切换：一条命令即可切换当前使用的 Node.js 版本
项目隔离：不同项目可以使用不同的 Node.js 版本
无需 sudo：nvm 安装在用户目录下，不需要管理员权限

2.4.2 安装 nvm

安装完成后，关闭并重新打开终端，或者执行：

验证 nvm 是否安装成功：

2.4.3 使用 nvm 安装 Node.js

2.4.4 nvm 常用命令

[!warning] nvm 与 Homebrew 不要混用
如果你选择使用 nvm 管理 Node.js，建议不要同时使用 Homebrew 安装 Node.js，这可能会导致版本冲突和路径问题。如果之前用 Homebrew 安装过 Node.js，建议先卸载：

2.5 方法三：官网下载安装

2.5.1 下载安装包

打开浏览器，访问 Node.js 官网：https://nodejs.org/

你会看到两个下载选项：

LTS（Long Term Support）：长期支持版本，稳定可靠，推荐大多数用户使用

Current：最新版本，包含最新特性，但可能不够稳定

点击 LTS 版本下载 .pkg 安装包

[!tip] 如何选择版本
选择 LTS 版本：如果你是普通用户或用于生产环境
选择 Current 版本：如果你想尝试最新特性，且不介意可能的不稳定性

2.5.2 安装步骤

双击下载的 .pkg 文件

按照安装向导的提示点击"继续"

阅读并同意许可协议

选择安装位置（默认即可）

点击"安装"，输入 Mac 密码确认

安装完成后点击"关闭"

2.6 验证 Node.js 安装

无论使用哪种方式安装，都需要验证安装是否成功：

[!success] 预期输出
$ node --version
v20.10.0

$ npm --version
10.2.3
版本号可能与上面不同，只要显示了版本号就说明安装成功。

3. npm 包管理器详解

3.1 什么是 npm

npm（Node Package Manager）是 Node.js 的默认包管理器，也是世界上最大的软件注册表。它用于：

安装软件包：从 npm 仓库下载并安装 JavaScript 包

管理依赖：跟踪项目所需的所有依赖包

发布软件包：将自己的代码发布到 npm 仓库供他人使用

运行脚本：执行 package.json 中定义的脚本命令

[!info] npm 与 Node.js 的关系
npm 是 Node.js 的"标配"工具，安装 Node.js 时会自动安装 npm。它们是相互独立的软件，但通常一起使用。

3.2 查看可安装的软件包版本

在安装任何 npm 软件包之前，你可能想知道有哪些版本可以安装。npm 提供了多种方式查看版本信息。

3.2.1 查看所有可用版本

3.2.2 查看最新版本

3.2.3 查看详细的版本信息

3.2.4 查看版本标签

3.3 安装特定版本的软件包

3.3.1 安装最新版本

3.3.2 安装指定版本

3.3.3 版本范围语法

npm 支持多种版本范围语法：

语法	含义	示例
`1.0.0`	精确版本	只安装 1.0.0
`^1.0.0`	兼容版本	安装 1.x.x 最新版（不改变主版本号）
`~1.0.0`	近似版本	安装 1.0.x 最新版（不改变次版本号）
`>=1.0.0`	大于等于	安装 1.0.0 或更高版本
`1.0.0 - 2.0.0`	版本范围	安装 1.0.0 到 2.0.0 之间的版本
`latest`	最新版	安装最新稳定版

3.4 查看已安装的软件包

3.5 更新软件包

3.6 切换软件包版本

npm 本身不支持像 nvm 那样直接"切换"版本，但你可以通过重新安装来切换：

[!tip] 版本切换最佳实践
如果你需要频繁在不同版本之间切换，建议：
1.
记录当前版本：在切换前记录当前使用的版本号
2.
了解版本差异：查看更新日志了解版本之间的差异
3.
测试兼容性：切换后测试关键功能是否正常

3.7 卸载软件包

3.8 npm 配置与镜像源

3.8.1 查看当前配置

3.8.2 配置国内镜像源

如果你在国内，npm 官方源可能较慢，可以配置国内镜像：

[!warning] 镜像源注意事项
镜像源可能有几分钟的同步延迟
某些私有包可能在镜像源上不可用
发布包时需要使用官方源

4. 安装 Claude Code

4.1 安装前检查

在安装 Claude Code 之前，确保你的环境满足要求：

[!warning] Node.js 版本要求
Claude Code 要求 Node.js 版本 >= 18.0.0。如果你的版本过低，请先升级 Node.js。

4.2 查看 Claude Code 可用版本

4.3 安装 Claude Code

4.3.1 标准安装（推荐）

命令解析：

部分	含义
`npm`	Node.js 包管理器
`install`	安装命令（可简写为 `i`）
`-g`	全局安装标志（`--global` 的简写）
`@anthropic-ai/claude-code`	软件包名称（`@anthropic-ai` 是组织名，`claude-code` 是包名）

4.3.2 安装特定版本

4.3.3 处理权限问题

[!error] 权限错误处理
如果安装时遇到 EACCES 权限错误，有以下几种解决方案：

方案一：使用 sudo（临时解决）

方案二：修改 npm 全局目录权限（推荐）

方案三：使用 nvm（最佳实践）

如果你使用 nvm 安装的 Node.js，通常不会有权限问题，因为 nvm 安装在用户目录下。

4.4 验证安装

[!success] 安装成功标志
如果 claude --version 显示了版本号，说明 Claude Code 已成功安装。
$ claude --version
claude-code version 1.0.50

4.5 更新 Claude Code

4.6 卸载 Claude Code

5. 配置环境变量

5.1 什么是环境变量

环境变量是操作系统中用于存储配置信息的键值对。程序可以读取这些变量来获取配置信息，而不需要在代码中硬编码。

[!info] 环境变量的作用
对于 Claude Code 来说，环境变量用于配置：
API 端点：Claude Code 连接的服务器地址
认证信息：API 密钥，用于验证身份
其他配置：如代理设置、日志级别等

5.2 Claude Code 需要的环境变量

变量名	用途	是否必需
`ANTHROPIC_BASE_URL`	API 服务器地址	是（使用中转服务时）
`ANTHROPIC_AUTH_TOKEN`	API 认证密钥	是（使用中转服务时）
`ANTHROPIC_API_KEY`	官方 API 密钥	是（使用官方服务时）

5.3 方法一：临时配置（当前终端会话）

临时配置只在当前终端窗口有效，关闭终端后失效。适合临时测试或一次性使用。

[!warning] 临时配置的局限性
只在当前终端窗口有效
打开新终端需要重新设置
重启电脑后失效
适合临时测试，不适合日常使用

5.4 方法二：永久配置（推荐）

永久配置会将环境变量写入 shell 配置文件，每次打开终端时自动加载。

5.4.1 确定使用的 Shell

5.4.2 配置 zsh（macOS 默认）

或者使用一行命令（适合复制粘贴）：

5.4.3 配置 bash

或者使用一行命令：

5.5 验证环境变量配置

[!tip] 打开新终端验证
配置永久环境变量后，建议打开一个新的终端窗口，再次验证环境变量是否生效。这能确保配置已正确写入配置文件。

5.6 环境变量配置流程图

上图展示了环境变量配置的完整流程。临时配置使用 export 命令，只在当前会话有效。永久配置需要根据使用的 Shell 类型编辑相应的配置文件（zsh 用户编辑 ~/.zshrc，bash 用户编辑 ~/.bash_profile），然后使用 source 命令使配置生效。配置完成后需要验证环境变量是否正确设置。

6. 启动与使用 Claude Code

6.1 基本启动

启动后，你会看到 Claude Code 的欢迎界面，可以开始与 AI 交互。

6.2 在项目目录中使用

Claude Code 会自动识别当前目录的项目上下文：

[!tip] 项目上下文的重要性
在项目目录中启动 Claude Code，AI 能够：
理解项目的目录结构
读取配置文件（package.json、pom.xml 等）
分析代码依赖关系
提供更精准的建议

6.3 常用命令和选项

6.3.1 命令行参数

6.3.2 交互模式中的斜杠命令

在 Claude Code 交互界面中，可以使用斜杠命令：

命令	功能
`/help`	显示帮助信息
`/clear`	清除对话历史
`/exit` 或 `/quit`	退出 Claude Code
`/model`	查看或切换模型
`/config`	查看或修改配置

6.4 使用示例

6.4.1 代码生成

> 创建一个 Python 函数，计算斐波那契数列的第 n 项

6.4.2 代码解释

> 解释 src/main.js 文件中的 handleSubmit 函数

6.4.3 Bug 修复

> 帮我检查 utils/validator.js 中的验证逻辑是否有问题

6.4.4 文档生成

> 为 src/api/user.js 中的所有函数生成 JSDoc 注释

7. 常见问题与解决方案

7.1 安装相关问题

7.1.1 npm 安装时权限错误（EACCES）

错误信息：

npm ERR! Error: EACCES: permission denied

解决方案：

7.1.2 网络超时或连接失败

错误信息：

npm ERR! network timeout
npm ERR! network request failed

解决方案：

7.1.3 Node.js 版本过低

错误信息：

error @anthropic-ai/claude-code@1.0.50: The engine "node" is incompatible with this module.

解决方案：

7.2 macOS 安全设置相关问题

7.2.1 系统阻止运行未知开发者的软件

问题描述：首次运行 claude 命令时，系统提示"无法打开，因为无法验证开发者"。

解决方案：

打开"系统偏好设置"（或"系统设置"）

点击"安全性与隐私"

在"通用"标签页下，点击"仍要打开"或"允许"

或者使用终端命令：

[!warning] 安全提示
禁用 Gatekeeper 会降低系统安全性，建议仅在必要时临时禁用，使用后立即重新启用。

7.3 环境变量相关问题

7.3.1 环境变量不生效

问题描述：设置了环境变量，但 echo $ANTHROPIC_BASE_URL 显示为空。

排查步骤：

7.3.2 API 密钥无效

问题描述：启动 Claude Code 时提示 API 密钥无效或认证失败。

排查步骤：

7.4 运行时问题

7.4.1 command not found: claude

问题描述：安装成功但运行 claude 命令提示找不到。

解决方案：

7.4.2 连接超时

问题描述：Claude Code 启动后连接服务器超时。

解决方案：

7.5 问题诊断流程图

上图展示了常见问题的诊断流程。首先根据问题类型进行分类（安装失败、无法启动、连接失败），然后根据具体的错误信息采取相应的解决方案。大多数问题都可以通过检查权限、网络配置、环境变量来解决。

8. 进阶配置

8.1 配置文件位置

Claude Code 的配置文件位于用户主目录下：

8.2 自定义 AI 行为

你可以创建 ~/.claude/CLAUDE.md 文件来自定义 Claude 的行为：

示例内容：

8.3 代理配置

如果你在需要代理的网络环境中，可以配置代理：

9. 总结

9.1 安装检查清单

在完成安装后，使用以下清单确认一切正常：

Node.js 已安装且版本 >= 18.0.0

npm 已安装且可正常使用

Claude Code 已全局安装

claude --version 显示版本号

环境变量 ANTHROPIC_BASE_URL 已设置

环境变量 ANTHROPIC_AUTH_TOKEN 已设置

claude 命令可以正常启动

9.2 快速参考命令

9.3 获取帮助

如果在使用过程中遇到问题：

查看官方文档：访问 Anthropic 官方文档获取最新信息

查看帮助命令：运行 claude --help 查看可用选项

社区支持：在 GitHub Issues 中搜索或提问

报告问题：https://github.com/anthropics/claude-code/issues

[!success] 恭喜完成安装
你已经成功安装并配置了 Claude Code！现在可以在终端中输入 claude 开始使用 AI 编程助手了。
享受 AI 辅助编程带来的效率提升吧！

1. 概述#

1.1 什么是 Claude Code#

1.2 适用场景#

1.3 系统要求#

1.4 安装流程概览#

2. 安装 Node.js 环境#

2.1 什么是 Node.js#

2.2 安装方式对比#

2.3 方法一：使用 Homebrew 安装（推荐）#

2.3.1 什么是 Homebrew#

2.3.2 检查是否已安装 Homebrew#

2.3.3 安装 Homebrew#

2.3.4 使用 Homebrew 安装 Node.js#

2.4 方法二：使用 nvm 安装（多版本管理）#

2.4.1 什么是 nvm#

2.4.2 安装 nvm#

2.4.3 使用 nvm 安装 Node.js#

2.4.4 nvm 常用命令#

2.5 方法三：官网下载安装#

2.5.1 下载安装包#

2.5.2 安装步骤#

2.6 验证 Node.js 安装#

3. npm 包管理器详解#

3.1 什么是 npm#

3.2 查看可安装的软件包版本#

3.2.1 查看所有可用版本#

3.2.2 查看最新版本#

3.2.3 查看详细的版本信息#

3.2.4 查看版本标签#

3.3 安装特定版本的软件包#

3.3.1 安装最新版本#

3.3.2 安装指定版本#

3.3.3 版本范围语法#

3.4 查看已安装的软件包#

3.5 更新软件包#

3.6 切换软件包版本#

3.7 卸载软件包#

3.8 npm 配置与镜像源#

3.8.1 查看当前配置#

3.8.2 配置国内镜像源#

4. 安装 Claude Code#

4.1 安装前检查#

4.2 查看 Claude Code 可用版本#

4.3 安装 Claude Code#

4.3.1 标准安装（推荐）#

4.3.2 安装特定版本#

4.3.3 处理权限问题#

4.4 验证安装#

4.5 更新 Claude Code#

4.6 卸载 Claude Code#

5. 配置环境变量#

5.1 什么是环境变量#

5.2 Claude Code 需要的环境变量#

5.3 方法一：临时配置（当前终端会话）#

5.4 方法二：永久配置（推荐）#

5.4.1 确定使用的 Shell#

5.4.2 配置 zsh（macOS 默认）#

5.4.3 配置 bash#

5.5 验证环境变量配置#

5.6 环境变量配置流程图#

6. 启动与使用 Claude Code#

6.1 基本启动#

6.2 在项目目录中使用#

6.3 常用命令和选项#

6.3.1 命令行参数#

6.3.2 交互模式中的斜杠命令#

6.4 使用示例#

6.4.1 代码生成#

6.4.2 代码解释#

6.4.3 Bug 修复#

6.4.4 文档生成#

7. 常见问题与解决方案#

7.1 安装相关问题#

7.1.1 npm 安装时权限错误（EACCES）#

7.1.2 网络超时或连接失败#

7.1.3 Node.js 版本过低#

7.2 macOS 安全设置相关问题#

7.2.1 系统阻止运行未知开发者的软件#

7.3 环境变量相关问题#

1. 概述

1.1 什么是 Claude Code

1.2 适用场景

1.3 系统要求

1.4 安装流程概览

2. 安装 Node.js 环境

2.1 什么是 Node.js

2.2 安装方式对比

2.3 方法一：使用 Homebrew 安装（推荐）

2.3.1 什么是 Homebrew

2.3.2 检查是否已安装 Homebrew

2.3.3 安装 Homebrew

2.3.4 使用 Homebrew 安装 Node.js

2.4 方法二：使用 nvm 安装（多版本管理）

2.4.1 什么是 nvm

2.4.2 安装 nvm

2.4.3 使用 nvm 安装 Node.js

2.4.4 nvm 常用命令

2.5 方法三：官网下载安装

2.5.1 下载安装包

2.5.2 安装步骤

2.6 验证 Node.js 安装

3. npm 包管理器详解

3.1 什么是 npm

3.2 查看可安装的软件包版本

3.2.1 查看所有可用版本

3.2.2 查看最新版本

3.2.3 查看详细的版本信息

3.2.4 查看版本标签

3.3 安装特定版本的软件包

3.3.1 安装最新版本

3.3.2 安装指定版本

3.3.3 版本范围语法

3.4 查看已安装的软件包

3.5 更新软件包

3.6 切换软件包版本

3.7 卸载软件包

3.8 npm 配置与镜像源

3.8.1 查看当前配置

3.8.2 配置国内镜像源

4. 安装 Claude Code

4.1 安装前检查

4.2 查看 Claude Code 可用版本

4.3 安装 Claude Code

4.3.1 标准安装（推荐）

4.3.2 安装特定版本

4.3.3 处理权限问题

4.4 验证安装

4.5 更新 Claude Code

4.6 卸载 Claude Code

5. 配置环境变量

5.1 什么是环境变量

5.2 Claude Code 需要的环境变量

5.3 方法一：临时配置（当前终端会话）

5.4 方法二：永久配置（推荐）

5.4.1 确定使用的 Shell

5.4.2 配置 zsh（macOS 默认）

5.4.3 配置 bash

5.5 验证环境变量配置

5.6 环境变量配置流程图

6. 启动与使用 Claude Code

6.1 基本启动

6.2 在项目目录中使用

6.3 常用命令和选项

6.3.1 命令行参数

6.3.2 交互模式中的斜杠命令

6.4 使用示例

6.4.1 代码生成

6.4.2 代码解释

6.4.3 Bug 修复

6.4.4 文档生成

7. 常见问题与解决方案

7.1 安装相关问题

7.1.1 npm 安装时权限错误（EACCES）

7.1.2 网络超时或连接失败

7.1.3 Node.js 版本过低

7.2 macOS 安全设置相关问题

7.2.1 系统阻止运行未知开发者的软件

7.3 环境变量相关问题

7.3.1 环境变量不生效