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 符合要求

第一步，先看看你的系统和 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 处理器，都是当前官方页面明确写着的。系统和这些条件对得上，就可以继续往下走；版本或架构不在范围内，先看看系统有没有升级路径。

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

第二步，执行 macOS、Linux、WSL 的推荐安装命令。 **入口在哪儿**？Claude Code 官方 Advanced setup 页的 Install Claude Code 部分，选中 ，找到 那个代码框。 **具体操作**：点代码框右侧的复制按钮，把官方命令直接粘贴到终端里执行。注意，别从第三方教程复制安装脚本，也别给原生命令额外加 sudo。 **成功了会怎样**？安装过程正常结束，用户目录下会多出一个可执行文件 ~/.local/bin/claude。重新打开终端后，就能继续做版本检查了。 **失败怎么办**？如果终端显示 HTML 解析错误、403 或 curl 错误，立刻停止当前操作，去官方安装排错页按错误文本匹配处理。权限出问题的话，先检查 ~/.local/bin 和 ~/.local/share 是不是属于当前用户，千万别用管理员权限强行覆盖。 图中选中的标签是 Native Install (Recommended)，macOS、Linux、WSL 共用同一个代码框。代码框复制按钮能正常取到命令，就说明入口可用；要是按钮或代码框没出现，先检查页面是否加载完整。

先验证二进制，再处理 PATH

第三步，检查版本号和只读诊断结果。 **入口**：安装结束后的新终端窗口。 **主要动作**：先跑 claude --version。能看到版本号之后，再跑 claude doctor 检查安装健康、设置文件错误和修复建议。 **成功标志**：版本命令打印出 Claude Code 的版本号；doctor 完成只读检查，没有提示二进制缺失或设置文件无效。 **失败处理**：如果版本命令提示找不到命令，别急着重复安装，先进入下一步检查 PATH。如果版本正常但 doctor 报警，按报警项修复设置或权限，别把 PATH 当成所有问题的统一原因。 ``` claude --version claude doctor ``` 官方验证区把两种检查分开了：版本号证明命令能启动，claude doctor 再检查安装和配置是否健康。两项都正常才算通过；只看到版本号或 doctor 报警时，继续检查设置与权限。 二进制和 PATH 得分开查。 第四步，判断 ~/.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

第五步，把用户级安装目录永久加入 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，再检查是不是写错了配置文件。 第六步，从项目目录启动 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 配置。