Claude Code 在 macOS 与 Linux 安装与 PATH 配置教程

安装器已经运行完，终端却提示“command not found: claude”，通常不是安装失败，而是当前 shell 没有搜索 ~/.local/bin。把安装、版本验证和 PATH 配置拆开检查，能很快分清二进制不存在、PATH 未生效和 shell 配置文件写错这三类问题。

完成后，你应当能在 macOS 或 Linux 的新终端窗口中运行 claude --version，用 claude doctor读取安装诊断，并在项目目录输入 claude启动交互会话。这里以官方推荐的原生安装为主，不把 VS Code 扩展内置的私有 CLI 当成系统级命令。

先确认系统和 shell 符合要求

1. 核对操作系统、处理器、内存和 shell。

   入口位置：Claude Code 官方 Advanced setup 页的 System requirements 部分，以及终端的系统信息。

   主要动作：确认 macOS 版本不低于 13；Linux 至少属于 Ubuntu 20.04、Debian 10、Alpine 3.19 或其兼容环境。机器需要 4 GB 以上内存、x64 或 ARM64 处理器、互联网连接，并能使用 Bash 或 Zsh。

   成功标志：系统版本和处理器架构在支持范围内，终端运行 echo $SHELL 能看到 Zsh 或 Bash 路径。

   失败处理：旧版 macOS 先升级系统；过旧 Linux 发行版先升级发行版。Alpine 还需准备 Bash、curl、libgcc、libstdc++ 和 ripgrep，缺少这些组件时不要直接执行安装。

看图中间的系统要求：macOS、Ubuntu、Debian、Alpine 的最低版本，4 GB 内存以及 x64、ARM64 处理器都由当前官方页面明确列出。系统与这些条件相符即可继续；版本或架构不在范围内时，先检查系统升级路径。

从官方代码框复制原生安装命令

2. 执行 macOS、Linux、WSL 的推荐安装命令。

   入口位置：Claude Code 官方 Advanced setup 页的 Install Claude Code 部分，选中 Native Install (Recommended)，找到 macOS, Linux, WSL 代码框。

   主要动作：点击代码框右侧的复制按钮，把当前官方命令粘贴到终端后执行。不要从第三方教程复制安装脚本，也不要给原生命令额外加 sudo。

   成功标志：安装过程正常结束，用户目录下出现可执行文件 ~/.local/bin/claude；重新打开终端后可以继续做版本检查。

   失败处理：若终端显示 HTML 解析错误、403 或 curl 错误，停止执行当前输出，回到官方安装排错页按错误文本匹配处理。权限错误时先检查 ~/.local/bin 与 ~/.local/share 是否属于当前用户，不要改用管理员权限覆盖。

图中选中的标签是 Native Install (Recommended)，macOS、Linux、WSL 共用同一代码框。代码框复制按钮可正常取到命令就表示入口可用；若按钮或代码框没有出现，先检查当前页面是否加载完整。

先验证二进制，再处理 PATH

3. 检查版本号和只读诊断结果。

   入口位置：安装结束后的新终端窗口。

   主要动作：先运行 claude --version。能看到版本后，再运行 claude doctor 检查安装健康、设置文件错误和修复建议。

   成功标志：版本命令打印 Claude Code 的版本号；doctor 完成只读检查，没有提示二进制缺失或设置文件无效。

   失败处理：若版本命令提示找不到命令，不要重复安装，先进入下一步检查 PATH。若版本正常而 doctor 报警，按报警项修复设置或权限，不要把 PATH 当成所有错误的统一原因。

claude --version
claude doctor

官方验证区把两种检查分开：版本号证明命令能启动，claude doctor 再检查安装和配置健康。两项都正常才算通过；只看到版本号或 doctor 报警时，继续检查设置与权限。

二进制和 PATH 要分开查。

4. 判断 ~/.local/bin 是否已经进入 PATH。

   入口位置：出现 command not found: claude 的同一个终端。

   主要动作：先确认原生安装文件确实存在，再逐行显示 PATH 并精确筛选 ~/.local/bin。这一步只读取状态，不修改任何配置。

   成功标志：test 命令显示二进制存在，PATH 检查打印当前用户的 .local/bin 绝对路径。

   失败处理：二进制不存在时，说明独立的终端版尚未安装；只安装 VS Code 扩展不会创建这个文件。二进制存在但 PATH 没输出时，再进入下一步修改 shell 配置。

test -x "$HOME/.local/bin/claude" && echo "Claude Code binary exists"
echo "$PATH" | tr ':' 'n' | grep -Fx "$HOME/.local/bin"

官方排错页说明了关键位置：macOS 和 Linux 的原生安装器把命令放在 ~/.local/bin/claude。该文件存在且 PATH 能找到它才算正常；若文件缺失，还要检查是否只安装了 VS Code 扩展。

Zsh 写入 .zshrc，Bash 写入 .bashrc

5. 把用户级安装目录永久加入 PATH。

   入口位置：先运行 echo $SHELL 确认当前 shell；macOS 默认通常是 Zsh，多数 Linux 终端使用 Bash。

   主要动作：Zsh 只执行 Zsh 代码块，Bash 只执行 Bash 代码块。命令会把 ~/.local/bin 放到现有 PATH 前面，再立即重新加载对应配置文件。

   成功标志：重新加载后，command -v claude 打印当前用户目录下的 .local/bin/claude，新开的终端也得到相同结果。

   失败处理：若没有生效，检查是否把配置写进了错误文件，或 PATH 行是否被后面的配置覆盖。不要同时向多个文件重复追加；先确定实际 shell，再保留一条有效配置。

Zsh：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

图中把 Zsh 与 Bash 两套命令放在同一官方区段。配置后新终端能找到 claude 才算成功；若仍找不到，先核对 echo $SHELL，再检查是否写错配置文件。

6. 从项目目录启动 Claude Code。

   入口位置：切换到准备使用 Claude Code 的项目根目录，再打开一个新终端窗口。

   主要动作：依次运行 command -v claude、claude --version 和 claude。首次启动时按终端提示完成登录和基础授权。

   成功标志：命令路径指向当前用户的安装位置，版本号正常显示，随后出现 Claude Code 交互会话。

   失败处理：若路径指向 Homebrew、npm 或旧目录，先检查重复安装和 shell 别名；若路径正确但程序无法启动，再运行 claude doctor，根据二进制、权限、网络或登录提示分别处理。

安装与 PATH 完成检查

• 系统版本、处理器、内存和 shell 均满足当前官方要求。
• 安装命令来自 Claude Code 官方 Advanced setup 页的 Native Install 代码框。
• ~/.local/bin/claude 存在且属于当前用户，不依赖管理员权限。
• Zsh 只修改 ~/.zshrc，Bash 只修改 ~/.bashrc，没有重复追加多条 PATH。
• command -v claude、claude --version 和 claude doctor 都能正常返回。
• 关闭并重新打开终端后仍能运行 claude，并能从项目目录进入交互会话。
• 页面内五张官方截图均能打开，分别对应系统要求、安装入口、版本验证、PATH 诊断和 PATH 配置。