Claude Code 是 Anthropic 官方出的终端编程助手，装上之后可以直接在命令行里读代码、改文件、跑测试、提交 commit。这篇记录在 Ubuntu 上把它装起来并跑通的完整流程，包含官方推荐的原生安装脚本、npm 和 apt 仓库三种方式，以及国内网络环境下要绕的坑。
一、环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Ubuntu 20.04 及以上（Debian 10+、Alpine 3.19+ 同样支持） |
| CPU / 内存 | x86_64 或 ARM64，建议 4 GB 以上内存 |
| Shell | bash 或 zsh |
| 网络 | 需要能访问 claude.ai 与 npmjs.org，国内直连通常不通，见第五节 |
| 账号 | Claude Pro / Max / Team / Enterprise 或 Console 账户，免费版 claude.ai 不含 Claude Code |
| ripgrep | 一般随安装包自带；若文件搜索异常可单独装 ripgrep |
二、安装前准备
先把软件源和基础工具补齐，全新系统往往连 curl 和 gnupg 都没有：
sudo apt update
sudo apt install -y curl gnupg git三、方式一：原生安装脚本（官方推荐）
不依赖 Node.js，安装后在后台自动更新，是目前最省心的方式：
curl -fsSL https://claude.ai/install.sh | bash需要稳定版通道或锁定具体版本时加参数：
# 稳定版通道
curl -fsSL https://claude.ai/install.sh | bash -s stable
# 锁定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89下载过程没有进度条，卡住几十秒是正常的。安装完成后启动器会被放在 ~/.local/bin/claude，实体文件在 ~/.local/share/claude/versions/ 下。如果运行时报 command not found，说明这个目录不在 PATH 里：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc四、方式二：npm 安装（Node.js 22+）
已经在用 Node 生态、或想和其他全局 CLI 统一管理时走这条。先确认版本：
node -v # 需要 v22 或更高Ubuntu 软件源自带的 Node 往往只有 18/20，用 NodeSource 装当前 LTS：
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v然后全局安装：
npm install -g @anthropic-ai/claude-code不要加 sudo。加了 sudo npm install -g 会把文件装成 root 所有，后续升级和插件安装都会踩权限问题（EACCES）。真遇到权限报错，正解是用 nvm 管 Node，或者把 npm 全局目录挪到自己家目录：
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code五、方式三：apt 仓库（系统级托管）
官方提供签名过的 apt 仓库，适合服务器批量部署。缺点是默认不自动更新，升级要跟着系统 apt upgrade 走。
第一步装依赖并导入签名密钥：
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
-o /etc/apt/keyrings/claude-code.asc校验密钥指纹，应当输出 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE：
gpg --show-keys /etc/apt/keyrings/claude-code.asc注册 stable 仓库并安装：
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
| sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code六、国内网络环境
卡点通常在两个地方：安装脚本要访问 claude.ai，登录授权要访问 Anthropic 的域名。三个思路按需选：
- 临时挂代理：
export https_proxy=http://127.0.0.1:7890 http_proxy=$https_proxy，装完unset https_proxy http_proxy收掉。服务器上长期跑就直接写进~/.bashrc。 - npm 走镜像：
npm config set registry https://registry.npmmirror.com，装完可以用npm config set registry https://registry.npmjs.org改回来。镜像只解决"下载"这一步，登录和模型调用仍然要网络可达。 - 实在装不上：换 apt 仓库方式，或者从有网络的机器上装好后把
~/.local/share/claude整个目录拷过来。
七、验证安装
claude --version
# 2.1.211 (Claude Code)
claude doctor
# 只读诊断：安装健康状况、配置文件校验错误、建议修复项claude doctor 比 --version 有用得多，怀疑装歪了就看它的输出。
八、首次登录授权
直接跑 claude，终端会抛出一个 URL，浏览器打开授权即可：
claude纯命令行的服务器没有浏览器，把 URL 复制到本机浏览器打开，授权完拿到验证码再粘回终端就行。用 API Key 的话，导出环境变量后启动时确认沿用密钥，就会跳过登录：
export ANTHROPIC_API_KEY="sk-ant-..."
claude九、升级与卸载
| 安装方式 | 升级 | 卸载 |
|---|---|---|
| 原生脚本 | 后台自动更新，无需操作 | rm -f ~/.local/bin/clauderm -rf ~/.local/share/claude |
| npm | npm install -g @anthropic-ai/claude-code@latest |
npm uninstall -g @anthropic-ai/claude-code |
| apt | sudo apt update && sudo apt upgrade claude-code |
sudo apt remove claude-code |
别用 npm update -g：它遵循首次安装时记录的 semver 范围，很多情况下升不到最新版，直接指定 @latest 更可靠。
十、常见报错
| 现象 | 原因与处理 |
|---|---|
claude: command not found |
安装目录不在 PATH。原生安装补 ~/.local/bin；npm 安装用 npm prefix -g 查实际全局目录 |
npm 安装报 EACCES |
权限问题，不要用 sudo 硬来，按第四节的 ~/.npm-global 或 nvm 方案改全局目录 |
apt 报 NO_PUBKEY BAA929FF1A7ECACE |
密钥没下载成功，检查能否访问 downloads.claude.ai 后重新导入 |
| 安装脚本卡住、返回 403 | 网络不可达，挂代理重试或改用 apt 方式 |
| 提示需要订阅 / 无法登录 | 免费版不含 Claude Code，需要 Pro 及以上订阅，或改用 Console API Key |
卸载后 claude 还能跑 |
存在第二份安装或旧 alias，type -a claude 能列出所有来源 |
小结
- 新装优先原生脚本，一条命令、自动更新，也不用操心 Node 版本；
- 要跟 Node 工具链一起管就走 npm，前提 Node ≥ 22，且绝不要 sudo；
- 批量部署的服务器用 apt 仓库，把升级交给系统流程；
- 国内环境先理顺代理，否则下载和授权两步都会卡死；装完用
claude doctor做体检。