安装流程结束后，终端却提示“command not found: claude”，不必立刻怀疑安装失败——很可能是因为当前 shell 没有将 ~/.local/bin 目录纳入 PATH 环境变量。 将安装、版本验证以及 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 部分，选择 Native Install (Recommended)，找到标有 macOS, Linux, WSL 的代码框。 **具体操作**：点击代码框右侧的复制按钮，将官方命令直接粘贴到终端中执行。注意：不要从第三方教程复制安装脚本，也不要为原生命令额外添加 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 配置。