摘要：Ubuntu、Debian、Fedora、Arch、Alpine——一篇覆盖五大 Linux 家族的 Claude Code 安装方法。包含发行版专属仓库（apt/dnf/AUR）、Linux 上独有的 Snap curl 陷阱、SELinux 权限问题、无头服务器配置、以及 claude setup-token 一年长效令牌的用法。
适用读者：所有 Linux 用户——从桌面开发者到无头服务器运维
前置知识：基本的终端操作，了解自己的 Linux 发行版
预计阅读时间：12 分钟
适用版本：Claude Code 2.x（2026 年 7 月），支持 Ubuntu 20.04+ / Debian 10+ / Fedora / RHEL 8+ / Arch / Alpine 3.19+

---

一、引言

Windows 篇发出后，Windows 用户说"终于有人讲清楚了"。

macOS 篇发出后，Mac 用户说"三分钟搞定，比想象中简单"。

然后 Linux 用户来了——

“我们不需要保姆级教程。给我们命令就行。”

行。这篇风格和前两篇不太一样——更直接、更硬核、覆盖更多发行版。但该提醒的坑一个不会少。毕竟 Linux 上有些问题（比如 Snap 版的 curl 导致安装失败），你不说，新手可能会卡半天。

---

二、开始之前

2.1 确认系统版本

cat /etc/os-release | head -4

支持的范围：

发行版	最低版本
Ubuntu	20.04 LTS
Debian	10 (Buster)
Fedora	当前版本
RHEL / Rocky / Alma	8.x
Arch	滚动更新
Alpine	3.19+

2.2 确认硬件和 Shell

# 内存（至少 4G）
free -h | head -2

# 当前 Shell
echo $SHELL

Claude Code 需要 Bash 或 Zsh。如果你在用 Fish 或其他 shell——没关系，Claude Code 本身能运行，但它 spawn 的子进程会用你的默认 shell，所以至少确保系统里装了 Bash。

---

三、通用方法：原生安装器（所有发行版适用）

这是最推荐的方式——一条命令，全发行版通用，自带 Node.js 运行时，后台自动更新。

curl -fsSL https://claude.ai/install.sh | bash

安装位置：~/.local/bin/claude

# 刷新 PATH（如果 shell 没自动加载）
source ~/.bashrc   # 或 source ~/.zshrc

# 验证
claude --version
# Claude Code v2.x.x

重要：不要用 sudo。 原生安装器只往你的 home 目录写东西，不需要 root 权限。用了 sudo 反而会把文件所有权搞乱。

⚠️ Ubuntu/Debian 用户特别注意：Snap 版 curl 的陷阱

如果你用的是 Ubuntu，有一个非常隐蔽的坑——系统里的 curl 可能是 Snap 版的。

Snap 的沙箱机制禁止 curl 写入隐藏目录（~/.claude/），导致安装脚本静默失败。

先检查：

which curl
# 如果是 /snap/bin/curl → 你中招了

修复：

sudo snap remove curl
sudo apt update && sudo apt install curl

然后重新执行安装命令。就这一个操作，省你半小时排查。

参考：GitHub Issue #28701

---

四、各发行版专属安装方法

如果你更喜欢用系统包管理器管理一切——以下是各发行版的官方仓库安装方式。

4.1 Ubuntu / Debian：apt 官方仓库

# 添加 GPG 密钥
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

# 添加仓库
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

GPG 指纹：31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE

更新：sudo apt update && sudo apt upgrade claude-code

4.2 Fedora / RHEL / Rocky / AlmaLinux：dnf 官方仓库

创建 /etc/yum.repos.d/claude-code.repo：

[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc

然后：

sudo dnf install claude-code

更新：sudo dnf update claude-code

4.3 Arch Linux：AUR

# 最新版
yay -S claude-code

# 稳定版（滞后约一周）
yay -S claude-code-stable

更新：yay -Syu claude-code（AUR 包不会自动更新）

4.4 Alpine Linux：额外依赖

Alpine 使用 musl libc 而不是 glibc，需要额外安装运行时依赖：

apk add libgcc libstdc++ ripgrep

然后创建一个配置，告诉 Claude Code 使用系统的 ripgrep：

mkdir -p ~/.claude
echo '{"env": {"USE_BUILTIN_RIPGREP": "0"}}' > ~/.claude/settings.json

最后用原生安装器：

curl -fsSL https://claude.ai/install.sh | bash

4.5 NixOS / Nix

NixOS 的不可变文件系统使得 curl | bash 模式不太合适。推荐方案：

# 用 npm 安装到用户目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
npm install -g @anthropic-ai/claude-code

# 在 home.nix 中添加 PATH
# home.sessionPath = [ "$HOME/.npm-global/bin" ];

---

各发行版方法总结

发行版	推荐方法	备选方法
Ubuntu / Debian	apt 官方仓库	原生安装器
Fedora / RHEL	dnf 官方仓库	原生安装器
Arch	AUR	原生安装器
Alpine	原生安装器 + 手动依赖	—
NixOS	npm 用户目录	—
其他	原生安装器	npm

---

五、首次启动与认证

桌面环境（有浏览器）：

cd ~/your-project
claude
# → 浏览器自动打开 → 登录 → 搞定

OAuth token 存储在 ~/.claude/.credentials.json（权限 0600），30 天自动续期。

5.1 无头服务器 / SSH / CI 环境

Linux 强项之一就是跑服务器。以下是无 GUI 环境的配置方式——

方案 A：API Key（最常用）

export ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# 非交互式运行
claude -p "分析这个项目的架构，列出所有模块"

方案 B：claude setup-token（一年长效令牌，订阅用户可用）

如果你有 Pro/Max 订阅但不想在服务器上配 API Key（API Key 走按量付费，不消耗订阅额度），可以用这个：

claude setup-token
# 输出一个一年有效期的令牌

export CLAUDE_CODE_OAUTH_TOKEN="上面输出的令牌"
claude -p "你的任务"

方案 C：API Key 存文件（比环境变量更安全）

echo 'sk-ant-api03-你的key' > ~/.claude/api-key
chmod 600 ~/.claude/api-key

# 在 .bashrc 里读取
export ANTHROPIC_API_KEY=$(cat ~/.claude/api-key)

---

六、Linux 上独有的坑与解决方案

问题 1：Snap 版 curl 导致安装失败

前面提过了，这里再强调一次——这是 Ubuntu 上最常见的问题。

curl -fsSL https://claude.ai/install.sh | bash
# curl: (23) client returned ERROR on write of 1369 bytes
# Download failed

解法：sudo snap remove curl && sudo apt install curl

问题 2：SELinux 阻止 Claude Code 执行

现象：Claude Code 启动后某些操作失败，/var/log/audit/audit.log 里有 denied 记录。

原因：SELinux（RHEL/Fedora 默认开启）阻止了 Claude Code 的某些文件操作。

排查：

sudo ausearch -m avc -ts recent | grep claude

临时验证（确认是不是 SELinux 导致的）：

sudo setenforce 0
# 重新跑 Claude Code，如果问题消失 → 确实是 SELinux
sudo setenforce 1  # 别忘了开回来！

永久修复（推荐）——不要关 SELinux，而是创建自定义策略允许 Claude Code：

# 收集 Claude Code 相关的 AVC 拒绝记录
sudo ausearch -m avc -ts recent | grep claude > /tmp/claude-avc.log
# 生成策略模块
sudo audit2allow -M claude-code -i /tmp/claude-avc.log
# 加载策略
sudo semodule -i claude-code.pp

如果你不确定怎么配——用原生安装器装到 ~/.local/bin/，用户目录下的操作一般不会被 SELinux 挡。

问题 3：AppArmor 限制（Ubuntu）

Ubuntu 默认用 AppArmor 而不是 SELinux。一般情况下 AppArmor 不会干扰用户目录下的程序，但如果你把 Claude Code 装到了系统路径（通过 apt 仓库），某些操作可能受限。

排查：

sudo aa-status | grep claude

如果有 claude 相关的 profile 在 enforce 模式——检查 /etc/apparmor.d/ 下的相关文件，调整或切换到 complain 模式：

sudo aa-complain /etc/apparmor.d/usr.bin.claude-code

问题 4：Wayland 环境下浏览器认证失败

现象：claude 启动后，浏览器没有自动打开，或者打开了但授权后无法跳回终端。

原因：某些 Wayland 合成器（特别是 Sway、Hyprland）下，xdg-open 的行为和 X11 下不太一样。

解法：

# 手动指定浏览器
export BROWSER="firefox"  # 或 google-chrome-stable

# 如果还不行，启动 claude 时会在终端显示一个 URL
# 手动复制 URL → 浏览器打开 → 授权 → 复制验证码 → 粘贴回终端

问题 5：沙箱环境（Flatpak/Snap 终端）

如果你用 Flatpak 版的终端模拟器（比如从 Flathub 装的 GNOME Terminal）——它可能无法正常访问宿主系统的文件。

解法：用发行版原生包管理器装的终端（sudo apt install gnome-terminal），不要用 Flatpak 版的。

问题 6：老旧 glibc 版本

现象：启动时报 GLIBC_X.XX not found。

原因：Claude Code 的预编译二进制需要较新的 glibc。

要求：

• Ubuntu 20.04 / Debian 10 及以上 → glibc 版本够用
• CentOS 7 → glibc 太老，不支持。升级到 Rocky 8+ 或 Alma 8+

检查：

ldd --version | head -1

---

七、服务器环境最佳实践

如果你在 Linux 服务器上跑 Claude Code（CI/CD、定时任务、自动化管道），几个建议：

7.1 用 claude -p 做一次性任务

# 非交互式，单次任务
claude -p "检查 src/ 下所有 Java 文件的异常处理是否完整"

# 输出到文件
claude -p "生成项目的 API 文档，Markdown 格式" > api-docs.md

7.2 设置超时和重试

# 任务超时 10 分钟
timeout 600 claude -p "重构这个模块的数据库访问层"

# 简单重试循环
for i in {1..3}; do
  claude -p "你的任务" && break
  echo "第 $i 次失败，10秒后重试..."
  sleep 10
done

7.3 限制资源使用

# 用 systemd-run 限制内存和 CPU
systemd-run --user --scope \
  -p MemoryMax=4G \
  -p CPUQuota=200% \
  claude -p "分析这个代码库"

7.4 用 claude doctor 做健康检查

# 部署后验证
claude doctor && echo "Claude Code healthy" || echo "Needs attention"

---

八、总结与下篇预告

本文要点

• 原生安装器一行搞定，全发行版通用——自带 Node.js，自动更新，不要 sudo
• Ubuntu 用户先确认 curl 不是 Snap 版——这是 Linux 上最大的坑，没有之一
• 发行版仓库（apt/dnf/AUR）适合系统级管理——统一升级、GPG 签名验证
• SELinux/AppArmor 挡路了不要直接关——创建策略模块才是正经做法
• 无头服务器用 API Key 或 claude setup-token——不需要浏览器也能跑
• claude doctor 是 Linux 上的排障利器——权限、PATH、网络，一跑就清楚

Linux 装完后的第一件事

和前面两篇一样——/init。 这套词我已经说了三篇了，但你如果真的跳过它，一个月后你会在某个深夜敲键盘抱怨"AI 怎么不懂我的项目"——到时候别说我没提醒你。

下篇预告

三大平台都装好了。但国内的朋友可能还有一个最关键的问题没解决——

“装好了，连不上。怎么办？”

下一篇——国内如何稳定使用 Claude Code。 网络问题、代理配置、API 中转、国内云服务商（阿里云/腾讯云）的 Claude 接入方案。前端时间社区吵得最凶的"Claude Code 在国内到底能不能用"，下篇给你一个诚实的答案。

---

参考资源：

• Claude Code 官方安装文档
• Claude Code Linux 各发行版指南
• Claude Code 安装故障排除
• GitHub Issue: Snap curl 导致安装失败

声明：本文基于 Claude Code 2.x（2026 年 7 月）编写，在 Ubuntu 24.04、Debian 12、Fedora 41、Arch（2026-07）上实测通过。各发行版仓库的可用性和包版本可能随 Anthropic 发布策略调整。Alpine 和 NixOS 的配置方案来自社区验证，建议结合自身环境测试。