🚀 阶段一：Claude Code CLI 零基础安装与环境修复

解决 90% 新手报错 | 100% 适配 Linux 服务器 | 全部命令可直接复制执行

📑 本章目录

前置依赖安装：Node.js 18+ 正版安装与校验
标准安装流程：全局安装、校验、升级
致命报错专项修复：claude: command not found
彻底重装方案：卸载残留清理、强制重装
登录与授权配置：API 密钥 / 会员双模式
环境验收标准：逐条校验命令
课后练习

1.1 前置依赖安装：Node.js 18+ 正版安装

原理讲解

Claude Code CLI 是一个 Node.js 包，通过 npm 全局安装。因此：

必须条件：Node.js ≥ 18.0.0（推荐 20.x LTS）
npm：随 Node.js 一同安装，版本需 ≥ 9.0.0
为什么不能用 apt 默认版：Ubuntu 22.04 的 apt install nodejs 只给 12.x，版本太低

实操命令：安装 Node.js 20.x LTS（推荐）

🎯 目标：在 Ubuntu/Debian 服务器上安装 Node.js 20.x LTS，确保版本满足 Claude Code CLI 要求。

# === 步骤1：更新系统包列表 ===
sudo apt update

# === 步骤2：安装必要工具（curl, gnupg） ===
sudo apt install -y curl gnupg

# === 步骤3：添加 NodeSource 官方仓库（Node.js 20.x LTS） ===
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# === 步骤4：安装 Node.js（同时自动安装 npm） ===
sudo apt install -y nodejs

命令释义

curl -fsSL：静默下载 Nodesource 安装脚本，-f 遇错即停，-s 不显示进度，-S 遇错显示，-L 跟随重定向
| sudo -E bash -：以 root 权限执行脚本，-E 保留当前环境变量
apt install -y nodejs：-y 跳过确认，适合脚本化安装

版本校验（必做！）

# 检查 Node.js 版本（必须 ≥ 18.0.0）
node --version
# 期望输出：v20.x.x 或 v18.x.x

# 检查 npm 版本（必须 ≥ 9.0.0）
npm --version
# 期望输出：10.x.x 或 9.x.x

⚠️ 易错点：如果 node --version 显示 v12.x.x 或更老，说明系统残留了旧版 Node.js。解决方案见 1.4 彻底重装方案。

备选方案：使用 nvm 安装（多版本管理场景）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重载 shell 配置
source ~/.bashrc

# 安装 Node.js 20 LTS
nvm install 20

# 设为默认版本
nvm alias default 20

# 使用该版本
nvm use 20

# 验证
node --version && npm --version

💡 建议：服务器环境推荐 NodeSource 仓库方式（更稳定）；开发机多项目场景推荐 nvm（灵活切换版本）。

1.2 标准安装流程：全局安装 Claude Code CLI

原理讲解

Claude Code CLI 通过 npm 全局安装，安装后会在系统的 node_modules 全局目录下放置包文件，并在 PATH 目录中创建 claude 可执行文件链接。理解这个机制有助于排查"命令不存在"问题。

实操命令

# === 全局安装 Claude Code CLI ===
npm install -g @anthropic-ai/claude-code

# === 安装过程预期输出 ===
# npm 会下载包并安装到全局 node_modules
# 最后一行显示：+ @anthropic-ai/claude-code@x.x.x

参数释义

npm install：npm 安装命令
-g：全局安装（global），包安装到系统级目录而非当前项目
@anthropic-ai/claude-code：包名，@anthropic-ai 是 npm 组织作用域（scope）

安装校验（必做！）

# 检查 claude 命令是否可用
claude --version
# 期望输出：版本号，如 1.0.x

# 查看 npm 全局包列表，确认已安装
npm list -g @anthropic-ai/claude-code
# 期望输出：/usr/lib/node_modules
# └── @anthropic-ai/claude-code@x.x.x

# 查看 claude 可执行文件位置
which claude
# 期望输出：/usr/bin/claude 或 /usr/local/bin/claude

升级命令

# === 升级到最新版本 ===
npm update -g @anthropic-ai/claude-code

# === 或：卸载后重装（更干净） ===
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# === 查看当前版本与最新版本对比 ===
npm outdated -g @anthropic-ai/claude-code

📌 升级频率建议：Claude Code CLI 更新频繁，建议每周执行一次 npm update -g @anthropic-ai/claude-code，或在遇到异常行为时首先尝试升级。

1.3 致命报错专项修复：`claude: command not found`

🔴 这是新手 TOP 1 报错！ 90% 的新手在安装后会遇到此问题。本节提供完整解决方案。

问题根因分析

npm 全局安装后，claude 可执行文件被放置在了 npm 的全局 bin 目录中（例如 /usr/local/lib/node_modules/.bin/ 或 ~/.npm-global/bin/），但该目录不在系统的 PATH 环境变量中，导致 shell 找不到该命令。

三种常见的 npm 全局路径模式：

root 权限安装：路径在 /usr/lib/node_modules/，bin 链接在 /usr/bin/
sudo 安装：路径在 /usr/local/lib/node_modules/，bin 链接在 /usr/local/bin/
用户级安装（nvm 或自定义 prefix）：路径在 ~/.npm-global/lib/node_modules/，bin 链接在 ~/.npm-global/bin/

诊断命令：先定位问题

# 步骤1：查看 npm 全局安装路径
npm config get prefix
# 输出示例：/usr/local 或 /home/username/.npm-global

# 步骤2：查看 npm 全局 bin 目录
npm bin -g
# 输出示例：/usr/local/bin 或 /home/username/.npm-global/bin

# 步骤3：检查该目录下是否有 claude
ls -la "$(npm bin -g)/claude"
# 如果文件存在，说明安装成功，只是 PATH 没配好

# 步骤4：检查当前 PATH 是否包含该目录
echo $PATH | tr ':' '\n' | grep "$(npm bin -g)"
# 无输出 = PATH 未包含 npm 全局 bin 目录 → 需要修复

修复方案一：标准服务器安装（root/sudo 方式）

# === 适用于使用 sudo npm install -g 安装的情况 ===

# 1. 确认 npm 全局 bin 路径
NPM_BIN=$(npm bin -g)
echo "npm 全局 bin 路径: $NPM_BIN"

# 2. 添加到 PATH（临时生效）
export PATH="$NPM_BIN:$PATH"

# 3. 测试 claude 命令
claude --version

# 4. 写入 ~/.bashrc 持久化
echo "export PATH=\"$NPM_BIN:\$PATH\"" >> ~/.bashrc

# 5. 重载配置
source ~/.bashrc

# 6. 再次验证
claude --version

修复方案二：nvm 用户

# === nvm 用户的 PATH 修复 ===

# 1. 确认 nvm 已加载
command -v nvm

# 2. 确认当前使用的 Node 版本
nvm current

# 3. 查看该版本下的 bin 目录
echo "$NVM_DIR/versions/node/$(nvm current)/bin"

# 4. 检查 claude 是否存在
ls -la "$NVM_DIR/versions/node/$(nvm current)/bin/claude"

# 5. 确保 ~/.bashrc 中有 nvm 初始化代码
# 如果缺失，添加以下内容：
cat >> ~/.bashrc << 'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
EOF

source ~/.bashrc
claude --version

修复方案三：自定义 npm prefix 用户

# === 适用于手动设置了 npm prefix 的情况 ===

# 1. 查看自定义 prefix
npm config get prefix

# 2. 如果你的 prefix 是 ~/.npm-global
# 确保以下内容在 ~/.bashrc 中：
cat >> ~/.bashrc << 'EOF'
# npm global settings
export NPM_CONFIG_PREFIX="$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
EOF

source ~/.bashrc
claude --version

⚠️ 常见陷阱

改了 ~/.bashrc 但没 source：修改后必须执行 source ~/.bashrc 或重新登录
改了 ~/.bashrc 但用的是 zsh：如果你用 zsh，要改 ~/.zshrc 而不是 ~/.bashrc
which claude 找到了但执行报错：可能是符号链接断裂，需要重装
sudo 安装后用普通用户执行：确保 /usr/local/bin 在普通用户的 PATH 中

1.4 彻底重装方案：卸载残留清理 + 强制重装

什么情况需要彻底重装？

安装过程被中断（网络断开、Ctrl+C）
版本升级后出现诡异报错
多版本残留导致命令行为异常
claude 能找到但执行时报模块找不到

完整重装流程（逐条执行）

# === 阶段1：卸载现有版本 ===
npm uninstall -g @anthropic-ai/claude-code

# === 阶段2：清理 npm 缓存 ===
npm cache clean --force

# === 阶段3：确认卸载干净 ===
which claude 2>/dev/null && echo "WARN: still exists" || echo "OK: removed"
npm list -g @anthropic-ai/claude-code 2>/dev/null && echo "WARN: still in npm" || echo "OK: removed"

# === 阶段4：手动清理残留文件（如果存在） ===
# 删除可能的残留可执行文件
sudo rm -f /usr/bin/claude /usr/local/bin/claude 2>/dev/null

# 删除可能的残留 node_modules
NPM_ROOT=$(npm root -g)
sudo rm -rf "$NPM_ROOT/@anthropic-ai/claude-code" 2>/dev/null

# === 阶段5：清理 npm 全局目录下的废弃包 ===
npm prune -g

# === 阶段6：重新安装 ===
npm install -g @anthropic-ai/claude-code

# === 阶段7：验证 ===
claude --version
# 期望输出：最新版本号

💡 如果你的服务器在国内，npm 下载可能很慢或失败。设置国内镜像：

# 设置淘宝 npm 镜像（临时）
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 或永久设置
npm config set registry https://registry.npmmirror.com

1.5 登录与授权配置

原理讲解

Claude Code CLI 支持两种认证模式：

模式	适用人群	认证方式
OAuth 登录	Claude Pro/Max 订阅用户	浏览器登录 Anthropic 账号
API 密钥	API 付费用户	设置 `ANTHROPIC_API_KEY` 环境变量

两种模式可同时配置，CLI 会优先使用 API 密钥。

模式一：OAuth 登录（推荐入门）

# 在终端执行登录命令
claude login

# 预期流程：
# 1. 终端输出一个验证链接
# 2. 浏览器打开链接（或手动复制到浏览器）
# 3. 在浏览器中登录 Anthropic 账号
# 4. 终端自动检测到登录成功
# 5. 显示 "Successfully logged in as <your-email>"

⚠️ 云服务器无浏览器的解决方案

# 方案1：使用 --print 参数获取验证链接，在本地浏览器打开
claude login --print

# 方案2：如果服务器有 lynx/links 文本浏览器
claude login

# 方案3：SSH 端口转发，用本地浏览器
# 在本地终端执行：
ssh -L 8080:localhost:8080 user@your-server
# 然后服务器上的 claude login 会在 localhost:8080 启动回调

模式二：API 密钥配置

# === 设置 API 密钥（临时，仅当前会话） ===
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# === 设置 API 密钥（持久化到 ~/.bashrc） ===
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"' >> ~/.bashrc
source ~/.bashrc

# === 验证密钥是否生效 ===
claude --version
# 如果能正常输出版本号，说明密钥格式正确

# 或使用 print 模式测试
echo "hello" | claude --print -p "say hello" 2>&1 | head -5

🔴 安全警告

不要把 API 密钥写在项目代码里！
不要把含密钥的 ~/.bashrc 上传到 git！
推荐使用 ~/.bashrc 或 ~/.claude/.env 存储密钥
API 密钥以 sk-ant-api03- 开头，如果格式不对会报认证错误

登录状态检查

# 检查当前登录状态
claude whoami
# 输出示例：Logged in as user@example.com (Pro)

# 切换账号：先登出再登录
claude logout
claude login

# 查看当前使用的认证方式
cat ~/.claude/config.json 2>/dev/null | grep -i auth || echo "使用环境变量认证"

查看和管理配置

# Claude Code CLI 配置目录
ls -la ~/.claude/
# credentials.json  - OAuth 登录凭证
# config.json        - 用户配置
# history.jsonl      - 会话历史

# 查看配置
cat ~/.claude/config.json 2>/dev/null || echo "尚未生成配置文件"

1.6 环境验收标准：逐条校验

🎯 完成以下所有检查项，方可确认环境安装成功。任一条不通过，请回溯对应章节修复。

# ========== 验收清单（逐条执行）==========

# ✅ 检查1：Node.js 版本 ≥ 18
node --version
# 期望：v18.x.x 或 v20.x.x 或更高

# ✅ 检查2：npm 版本 ≥ 9
npm --version
# 期望：9.x.x 或 10.x.x

# ✅ 检查3：claude 命令存在
which claude
# 期望：/usr/bin/claude 或 /usr/local/bin/claude 或 ~/.npm-global/bin/claude

# ✅ 检查4：claude 版本正常输出
claude --version
# 期望：输出版本号，无报错

# ✅ 检查5：claude --help 正常输出
claude --help | head -5
# 期望：显示帮助信息

# ✅ 检查6：登录状态正常
claude whoami 2>/dev/null || echo "使用 API 密钥模式，跳过此检查"

# ✅ 检查7：能进入交互模式
# 在终端执行 claude，应该出现交互提示符
# 输入 /exit 退出
echo "测试交互模式：执行 claude 后输入 /exit 退出"

# ✅ 检查8：print 模式正常工作
echo "" | claude --print -p "回复 OK" 2>&1 | head -3
# 期望：输出包含 OK

💡 一键验收脚本：将上述检查保存为脚本执行。

#!/bin/bash
# 保存为 check-claude-env.sh，执行 bash check-claude-env.sh
echo "=== Claude Code CLI 环境检查 ==="
check() { echo -n "检查 $1... "; eval "$2" && echo "✅ 通过" || echo "❌ 失败"; }
check "Node.js版本" 'node --version | grep -qE "v(1[89]|2[0-9])"'
check "npm版本" 'npm --version | grep -qE "^[0-9]+"'
check "claude命令" 'which claude > /dev/null 2>&1'
check "claude版本" 'claude --version > /dev/null 2>&1'
check "claude帮助" 'claude --help > /dev/null 2>&1'
echo "=== 检查完成 ==="

1.7 课后练习

安装练习：在全新 Ubuntu 22.04 服务器上完成从零到可用的完整安装流程
排错练习：故意移除 PATH 中的 npm bin 路径，观察报错，然后修复
重装练习：执行完整卸载 → 重装流程，确认版本号一致
双模式练习：分别配置 OAuth 登录和 API 密钥模式，理解两种模式的差异
脚本编写：写一个一键安装脚本，在新服务器上 3 分钟内完成全流程配置
镜像切换：配置 npm 淘宝镜像，测试下载速度差异
nvm 切换：如果使用 nvm，练习在不同 Node.js 版本间切换，验证 claude 命令的可用性

🚀 阶段一：Claude Code CLI 零基础安装与环境修复

1.1 前置依赖安装：Node.js 18+ 正版安装

原理讲解

实操命令：安装 Node.js 20.x LTS（推荐）

版本校验（必做！）

备选方案：使用 nvm 安装（多版本管理场景）

1.2 标准安装流程：全局安装 Claude Code CLI

原理讲解

实操命令

安装校验（必做！）

升级命令

1.3 致命报错专项修复：claude: command not found

问题根因分析

诊断命令：先定位问题

修复方案一：标准服务器安装（root/sudo 方式）

修复方案二：nvm 用户

修复方案三：自定义 npm prefix 用户

1.4 彻底重装方案：卸载残留清理 + 强制重装

什么情况需要彻底重装？

完整重装流程（逐条执行）

1.5 登录与授权配置

原理讲解

模式一：OAuth 登录（推荐入门）

模式二：API 密钥配置

登录状态检查

查看和管理配置

1.6 环境验收标准：逐条校验

1.7 课后练习

1.3 致命报错专项修复：`claude: command not found`