教程►Linux/开发工具

Claude Code 安装菜鸟教程（Ubuntu 24.04 + nvm + 国内镜像源）

Claude Code 安装菜鸟教程（Ubuntu 24.04 + nvm + 国内镜像源）

本文记录在一台 Ubuntu 24.04 LTS 机器上安装 Claude Code（Anthropic 官方的终端 AI 编程工具）的全过程，版本 2.1.280。

写这篇的原因是：安装本身只有一条命令，但这条命令在国内网络环境下几乎必卡，而且装完之后大概率会遇到「明明提示安装成功，claude 命令却找不到」的情况。下面把每一步的命令、原因、预期输出和排查方法都写清楚。

适用环境：Ubuntu 24.04.5 LTS / Node v24.21.0（nvm 安装）/ npm 11.19.0 / Claude Code 2.1.280
适合人群：第一次在 Linux 上装 Claude Code，想知道每条命令在干什么

一、Claude Code 是什么

一句话：跑在终端里的 AI 编程助手。它不像 IDE 插件那样需要打开编辑器，而是直接在命令行里读你的项目、改代码、跑命令、提交 Git。

它的分发方式是一个 npm 包：@anthropic-ai/claude-code。核心是一个 200 多 MB 的原生二进制（不是纯 JS），所以装的时候会按平台拉取对应的二进制包。

前置条件：Node.js 18 及以上。就这么一个要求，没有别的依赖。

二、安装前：检查环境

先确认 Node 和 npm 在位、版本达标：

1
2
node -v    # 预期：v24.21.0（>= 18 即可）
npm -v     # 预期：11.19.0

顺便确认系统版本（后面排查会用到）：

1
cat /etc/os-release | head -3   # PRETTY_NAME="Ubuntu 24.04.5 LTS"

如果 node -v 报 command not found，说明还没装 Node，先装。推荐用 nvm（可以在多个 Node 版本间切换，且不需要 root 权限）：

1
2
3
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

三、关键决策：要不要换镜像源

这是整篇文章最实用的一段。

Claude Code 的官方安装命令是：

1
npm install -g @anthropic-ai/claude-code

在国内网络下直接跑这条，大概率表现为「卡住不动」——终端没有报错，也没有进度，就那么停着，直到超时。

为什么会这样？可以自己测一下两个源的实际响应速度：

1
2
3
4
5
6
7
# 测试官方源
timeout 12 curl -s -o /dev/null -w "耗时:%{time_total}s 状态:%{http_code}\n" \
  https://registry.npmjs.org/@anthropic-ai%2fclaude-code

# 测试国内镜像（淘宝 npmmirror）
timeout 12 curl -s -o /dev/null -w "耗时:%{time_total}s 状态:%{http_code}\n" \
  https://registry.npmmirror.com/@anthropic-ai%2fclaude-code

本机实测结果：

源 结果
官方源 registry.npmjs.org 超时，12 秒无响应
国内镜像 registry.npmmirror.com 7.1 秒返回 200

所以安装命令要带上镜像参数。推荐用一次性参数（只影响这一条命令，不改动全局配置）：

1
2
3
npm install -g @anthropic-ai/claude-code \
  --registry=https://registry.npmmirror.com \
  --no-audit --no-fund

参数解释：

  • --registry=...：本次安装从指定源下载。
  • --no-audit：跳过安全审计，能省几十秒。
  • --no-fund：不打印赞助信息。

如果你想一劳永逸地换源（之后所有 npm 命令都走镜像）：

1
2
3
npm config set registry https://registry.npmmirror.com
# 恢复官方源：
# npm config set registry https://registry.npmjs.org

安装过程约 2 分钟（主要是下载那个 200MB+ 的二进制）。看到 changed 2 packages 就说明成功了。

四、安装后：验证

1
claude --version

预期输出：

1
2.1.280 (Claude Code)

如果这里报 claude: command not found，不要慌，也不要重装，直接跳到第六节的坑 3，那是 PATH 问题，不是安装失败。

五、三个坑（按踩到的概率排序）

坑 1：命令看起来卡死（最常见）

现象：执行安装命令后终端长时间无输出。

原因：npm 在从官方源下载，网络不通就会一直挂着（npm 默认超时较长，期间不打进度）。

解决：按第三节换成国内镜像源。也可以加 --loglevel=http，让它把每次 HTTP 请求打出来，至少有东西在动，方便判断是真的在下载还是已经卡死：

1
2
3
npm install -g @anthropic-ai/claude-code \
  --registry=https://registry.npmmirror.com \
  --no-audit --no-fund --loglevel=http

坑 2：不要加 sudo

现象：网上有些教程写 sudo npm install -g ...。

为什么不该加：如果你用 nvm 装的 Node，那么 npm 的全局目录在你自己的家目录里，本来就可写，加 sudo 纯属多余，而且会让包文件的属主变成 root，以后更新、卸载都会遇到权限麻烦。

怎么判断自己的全局目录在哪、需不需要 sudo：

1
npm config get prefix
  • 输出形如 /home/你的用户名/.nvm/versions/node/vXX/bin → 用户目录，不要 sudo。
  • 输出形如 /usr/local 或 /usr → 系统目录，才需要考虑 sudo（更推荐改成用 nvm 或配置 npm 的用户级目录）。

想确认目录是否可写，实测一次最准：

1
touch /usr/local/lib/node_modules/.wtest && echo "可写" || echo "不可写"

坑 3：安装成功但 claude 命令找不到（最容易误判）

现象：安装输出显示成功，但执行下面这条没有任何返回：

1
2
which claude       # 空输出
claude --version   # bash: claude: command not found

原因：Claude Code 被装到了 nvm 的 Node 版本目录下：

1
~/.nvm/versions/node/v24.21.0/bin/claude

而这个目录是由 nvm 在每次启动交互式 shell 时动态加入 PATH 的。nvm 的加载代码写在 ~/.bashrc 里，而 .bashrc 只在交互式终端中执行。所以在某些非交互场景（脚本、IDE 内置终端、远程执行）里，PATH 里就没有这个目录。

排查三步：

1
2
3
4
5
6
7
8
# 1. 先看 PATH 里有没有 nvm 的目录
echo $PATH

# 2. 用绝对路径直接测试二进制本身（能跑就说明装好了）
~/.nvm/versions/node/v24.21.0/bin/claude --version

# 3. 确认 .bashrc 里有 nvm 的加载代码
grep -n "nvm" ~/.bashrc

第 2 步能输出版本号，就证明程序是好的，只是 PATH 没配。

解决方法（选一个）：

最简单——打开一个新的终端窗口再试。新终端会完整加载 .bashrc，nvm 会把 PATH 配好。

如果新终端还是不行，就把路径写死进 .bashrc：

1
2
echo 'export PATH="$HOME/.nvm/versions/node/v24.21.0/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

注意上面那行里的版本号 v24.21.0 要换成你自己的实际版本（node -v 查）。以后用 nvm 切换 Node 版本，记得同步改这一行。

六、关于安装时的一个警告（可忽略）

npm 11 安装结束时可能会看到：

1
2
npm warn install-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn install-scripts   @anthropic-ai/claude-code@2.1.280 (postinstall: node install.cjs)

这是 npm 新版本的安全策略：默认不自动执行包的 postinstall 脚本，需要显式授权。

实际检查下来，二进制和命令链接都已经正确就位了（bin/claude.exe 存在，bin/claude 软链已建），功能不受影响，可以不管。

如果你确实想让它跑一遍那个脚本：

1
npm install -g @anthropic-ai/claude-code --allow-scripts=@anthropic-ai/claude-code

七、首次启动与登录

1
claude

首次运行会引导登录，两种方式二选一：

  1. Anthropic 账号登录（订阅用户）：浏览器授权后回终端。
  2. API Key：设置环境变量 ANTHROPIC_API_KEY。

重要：Claude Code 是交互式 TUI 程序，需要真正的终端（TTY）才能运行。在 CI 脚本、或被 timeout/管道包裹的非交互环境里跑会失败或异常退出。

八、常用命令速查

1
2
3
4
5
6
7
8
claude --version                 # 查看版本
claude                           # 在当前目录启动交互会话
claude -p "解释这个项目结构"      # 非交互模式，直接问一个问题并输出结果
claude update                    # 升级到最新版
npm update -g @anthropic-ai/claude-code   # 或用 npm 升级

# 卸载
npm uninstall -g @anthropic-ai/claude-code

九、一句话总结

1
2
3
4
5
6
7
8
# 检查
node -v

# 安装（国内镜像，不加 sudo）
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com --no-audit --no-fund

# 验证（新开终端）
claude --version

三个要记住的点：国内必须换源；nvm 用户不要加 sudo；命令找不到先查 PATH，别急着重装。