Claude Code Linux/WSL2 系统完整安装指南

系统要求

最低配置

操作系统:
- Ubuntu 20.04+ / Debian 10+
- Fedora 33+ / CentOS 8+
- Arch Linux / Manjaro
- Alpine Linux 3.14+
- WSL 1 或 WSL 2
内存: 至少 4GB RAM（推荐 8GB+）
存储空间: 至少 500MB 可用空间
网络: 需要互联网连接（用于 API 调用和更新）

必需软件

Shell: Bash、Zsh 或 Fish
curl: 用于下载安装脚本
基础工具: glibc、libstdc++

Linux 发行版支持

Claude Code 支持所有主流 Linux 发行版，但不同发行版可能有特殊要求。

Ubuntu / Debian 系列

完全支持的版本:

Ubuntu 20.04 LTS, 22.04 LTS, 23.04+
Debian 10 (Buster), 11 (Bullseye), 12 (Bookworm)
Linux Mint 20+
Pop!_OS 20.04+

特点:

无需额外依赖
apt 包管理器
安装最简单

Fedora / RHEL / CentOS 系列

完全支持的版本:

Fedora 33+
RHEL 8+
CentOS Stream 8+
Rocky Linux 8+
AlmaLinux 8+

特点:

dnf/yum 包管理器
可能需要启用 EPEL 仓库

Arch Linux 系列

完全支持的版本:

Arch Linux
Manjaro
EndeavourOS

特点:

滚动更新
pacman 包管理器
通常已包含所需依赖

Alpine Linux

支持版本: Alpine Linux 3.14+

特别注意:

使用 musl libc 而非 glibc
需要额外安装依赖包
需要禁用内置 ripgrep

其他发行版

openSUSE: Leap 15.3+, Tumbleweed
Gentoo: 完全支持
NixOS: 需要特殊配置
Void Linux: 完全支持

WSL2 安装指南

Windows Subsystem for Linux (WSL) 允许在 Windows 上运行 Linux 环境。推荐使用 WSL 2，性能更好。

安装前准备

系统要求与基础配置

操作系统: Windows 11 或 Windows 10 21H2 以上版本
系统版本: 专业版/工作站版/企业版（家庭版不支持 Hyper-V，但可以使用 WSL2）
硬件要求: CPU 需支持虚拟化技术并在 BIOS 中已启用

判断电脑是否开启虚拟化

按 Ctrl + Shift + Esc 打开任务管理器
切换到"性能" → "CPU"
在右下角可以看到"虚拟化：已启用/已禁用"

开启虚拟化功能（关键步骤！）

如果虚拟化显示为"已禁用"，需要在 BIOS 中启用：

重启电脑，开机时按 F2 或 Del 键进入 BIOS/UEFI 设置
- 不同品牌电脑按键可能不同：Dell: F2, HP: F10/Esc, Lenovo: F1/F2, ASUS: F2/Del
找到 Intel (VMX) Virtualization Technology 或 AMD-V 选项（通常在 "Advanced" → "CPU Configuration" 菜单中）
设置为 Enabled（启用）
保存设置并退出重启（通常按 F10 保存）

启用 Windows 功能

方法一: 通过图形界面（推荐新手）

按 Win + R，输入 optionalfeatures 并回车
或打开"控制面板" → "程序与功能" → "启用或关闭 Windows 功能"
勾选以下两项：
- ☑ 虚拟机平台 (Virtual Machine Platform)
- ☑ 适用于 Linux 的 Windows 子系统 (Windows Subsystem for Linux)
点击"确定"并重启电脑

方法二: 通过 PowerShell（推荐高级用户）

以管理员身份打开 PowerShell，运行：

                    # 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑
Restart-Computer
                

步骤 1: 在 Windows 上安装 WSL 2

检查 WSL 版本

打开 PowerShell 或命令提示符，运行：

wsl --version

如果显示版本信息，说明已安装 WSL 2。

全新安装 WSL 2 (Windows 10 2004+ 或 Windows 11)

以管理员身份打开 PowerShell，运行：

                    # 一键安装 WSL 2 和 Ubuntu
wsl --install
                

这会自动：

启用 WSL 功能
安装 WSL 2 Linux 内核
设置 WSL 2 为默认版本
安装 Ubuntu 发行版

从 WSL 1 升级到 WSL 2

                    # 设置 WSL 2 为默认版本
wsl --set-default-version 2

# 将已安装的发行版转换为 WSL 2
wsl --set-version Ubuntu 2

# 验证版本
wsl -l -v
                

预期输出:

                      NAME      STATE           VERSION
* Ubuntu    Running         2
                

步骤 2: 选择并安装 Linux 发行版

查看可用发行版

wsl --list --online

安装特定发行版

                    # 安装 Ubuntu 22.04
wsl --install -d Ubuntu-22.04

# 安装 Debian
wsl --install -d Debian

# 安装 Arch Linux
wsl --install -d Arch
                

步骤 3: 首次设置 Ubuntu

启动 Ubuntu

在开始菜单中搜索 "Ubuntu 20.04 LTS" 或 "Ubuntu 22.04 LTS"
首次运行会自动初始化，需要等待 1-2 分钟

创建用户名和密码

首次运行会提示创建 Linux 用户：

                    Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username:
                

重要提示:

用户名: 建议使用英文小写，不要使用中文或特殊字符
密码: 输入时不会显示任何字符（包括 *），这是正常的安全机制
记住密码: 这个密码在使用 sudo 时会用到，务必记住

更新系统软件包

首次设置完成后，建议立即更新系统：

                    # 更新软件包列表
sudo apt update

# 升级已安装的软件包
sudo apt upgrade -y
                

步骤 4: 在 WSL 中安装 Claude Code

方法一: 使用一键安装脚本（推荐）

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

方法二: 使用 npm 安装

1. 安装 Node.js 环境

                    # 添加 NodeSource 仓库（Node.js 22.x LTS）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

# 验证安装（应显示 v22.x 和 10.x）
node --version
npm --version
                

2. 安装 Claude Code

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

3. 验证安装

claude --version

步骤 5: WSL 特别配置

配置 WSL 2 内存限制

创建或编辑 C:\Users\你的用户名\.wslconfig：

                    [wsl2]
memory=4GB
processors=2
swap=2GB
                

保存后重启 WSL：

                    wsl --shutdown
wsl
                

WSL 与 Windows 文件系统互操作

WSL 可以访问 Windows 文件系统：

                    # Windows C 盘映射到 /mnt/c
cd /mnt/c/Users/你的用户名/Documents

# 在 Windows 项目中使用 Claude Code
cd /mnt/c/Projects/my-app
claude
                

从 Windows 访问 WSL 文件系统：

在文件资源管理器地址栏输入: \\wsl$\Ubuntu\home\你的用户名

Linux 原生安装

方式一: 一键安装脚本（推荐）

这是最简单的安装方式，适合所有主流发行版。

步骤 1: 确保已安装 curl

Ubuntu/Debian:

                    sudo apt update
sudo apt install curl -y
                

Fedora/RHEL/CentOS:

sudo dnf install curl -y

Arch Linux:

sudo pacman -S curl

Alpine Linux:

sudo apk add curl

步骤 2: 执行安装脚本

安装最新稳定版本:

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

安装指定版本:

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

安装最新开发版:

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

方式二: Alpine Linux 专用安装

Alpine Linux 使用 musl libc，需要额外配置。

步骤 1: 安装必需依赖

                    # 安装基础依赖
sudo apk add libgcc libstdc++

# 安装 ripgrep（代替内置版本）
sudo apk add ripgrep
                

步骤 2: 设置环境变量

                    # 禁用内置 ripgrep
export USE_BUILTIN_RIPGREP=0

# 永久设置
echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.profile
                

步骤 3: 运行安装脚本

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

方式三: 手动下载安装

步骤 1: 下载二进制文件

使用 wget 下载对应架构的文件：

                    # 下载 x64 版本
wget https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64

# 下载 ARM64 版本
wget https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-arm64
                

步骤 2: 安装到本地目录

                    # 创建安装目录
mkdir -p ~/.local/bin

# 移动文件并重命名
mv claude-linux-x64 ~/.local/bin/claude

# 添加执行权限
chmod +x ~/.local/bin/claude
                

方式四: 使用 Node.js/npm 安装

步骤 1: 安装 Node.js 环境

Ubuntu/Debian 系统

                    # 添加 NodeSource 仓库（Node.js LTS）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs
                

Fedora/RHEL/CentOS 系统

sudo dnf install nodejs npm -y

Arch Linux 系统

sudo pacman -S nodejs npm

验证安装

                    node --version
npm --version
                

步骤 2: 安装 Claude Code

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

# 如果遇到权限问题
sudo npm install -g @anthropic-ai/claude-code
                

步骤 3: 验证安装

claude --version

环境配置

安装完成后，需要配置 PATH 环境变量。

配置 PATH 环境变量

自动配置（推荐）

大多数情况下，安装脚本已自动配置。验证一下：

echo $PATH | grep ".local/bin"

如果有输出，说明已配置成功。

手动配置 - Bash 用户

编辑 ~/.bashrc：

nano ~/.bashrc

在文件末尾添加：

                    # 添加 Claude Code 到 PATH
export PATH="$HOME/.local/bin:$PATH"
                

保存并使配置生效：

source ~/.bashrc

手动配置 - Zsh 用户

编辑 ~/.zshrc：

nano ~/.zshrc

添加相同的配置：

                    # 添加 Claude Code 到 PATH
export PATH="$HOME/.local/bin:$PATH"
                

保存并生效：

source ~/.zshrc

手动配置 - Fish 用户

编辑 ~/.config/fish/config.fish：

nano ~/.config/fish/config.fish

添加：

                    # 添加 Claude Code 到 PATH
set -gx PATH $HOME/.local/bin $PATH
                

保存并生效：

source ~/.config/fish/config.fish

系统级配置（所有用户）

如果希望所有用户都能使用 Claude Code：

                    # 需要 sudo 权限
sudo cp ~/.local/bin/claude /usr/local/bin/
sudo chmod +x /usr/local/bin/claude
                

API 配置

Claude Code 需要 Anthropic API Key 才能正常工作。

获取 API Key

官方 API

访问 https://console.anthropic.com/
登录或注册账号
进入 "API Keys" 页面
点击 "Create Key" 创建新的 API 密钥
复制生成的密钥（格式: sk-ant-api03-...）

中转 API（国内推荐）

如果你在中国大陆，可以使用中转服务：

访问中转服务商网站（如 https://api.nekoapi.com/）
注册账号并充值
获取中转 API Key 和 Base URL

配置方式

Bash 用户配置

编辑 ~/.bashrc：

nano ~/.bashrc

在文件末尾添加：

                    # Claude Code API 配置
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

# 如果使用中转服务
export ANTHROPIC_BASE_URL="https://api.claudecode.net.cn/api/claudecode"

# Auth Token（与 API Key 相同）
export ANTHROPIC_AUTH_TOKEN="sk-ant-api03-你的密钥"
                

保存并生效：

source ~/.bashrc

Zsh 用户配置

编辑 ~/.zshrc：

nano ~/.zshrc

添加相同的环境变量，保存后运行：

source ~/.zshrc

Fish 用户配置

编辑 ~/.config/fish/config.fish：

nano ~/.config/fish/config.fish

添加：

                    # Claude Code API 配置
set -gx ANTHROPIC_API_KEY "sk-ant-api03-你的密钥"
set -gx ANTHROPIC_BASE_URL "https://api.claudecode.net.cn/api/claudecode"
set -gx ANTHROPIC_AUTH_TOKEN "sk-ant-api03-你的密钥"
                

保存并生效：

source ~/.config/fish/config.fish

验证配置

                    echo $ANTHROPIC_API_KEY
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN
                

应该显示你配置的值。

配置说明

ANTHROPIC_BASE_URL: API 服务器地址
- 官方: https://api.anthropic.com 或不设置
- 中转: 使用中转商提供的 URL
ANTHROPIC_API_KEY: 你的 API 密钥（格式通常为 sk-ant-api03- 开头）
ANTHROPIC_AUTH_TOKEN: 认证令牌（通常与 API KEY 相同）

验证安装

配置完成后，验证 Claude Code 是否正常工作。

步骤 1: 打开新的终端

重要：必须打开新的终端窗口或重新加载配置，让环境变量生效。

                    # Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

# Fish
source ~/.config/fish/config.fish
                

步骤 2: 检查版本

claude --version

预期输出:

Claude Code v1.0.58

步骤 3: 检查安装位置

which claude

预期输出:

/home/username/.local/bin/claude

步骤 4: 系统诊断

claude doctor

此命令会检查：

Claude Code 版本
安装类型（原生 vs npm）
API 配置状态
网络连接
Shell 环境
系统依赖

步骤 5: 测试运行

claude "你好，Claude！"

如果一切正常，Claude 会回复你的问候，说明安装和配置都成功了。

常见问题

Q1: 提示 "command not found: claude"

原因: PATH 环境变量未正确配置。

解决方法:

检查 PATH: echo $PATH | grep ".local/bin"
如果没有输出，重新配置 PATH
确保重新加载配置: source ~/.bashrc
验证安装位置: ls -la ~/.local/bin/claude
确保有执行权限: chmod +x ~/.local/bin/claude

Q2: WSL 中找不到 claude 命令

原因: WSL 环境变量未正确加载。

解决方法:

确保在 WSL 终端而非 Windows 终端: uname -a（应显示 Linux 内核信息）
重新加载配置: source ~/.bashrc
检查文件是否存在: ls -la ~/.local/bin/claude
如果不存在，重新安装: curl -fsSL https://claude.ai/install.sh | bash

Q3: Alpine Linux 安装失败

症状: 提示缺少共享库或 ripgrep 错误。

解决方法:

安装所需依赖: sudo apk add libgcc libstdc++ ripgrep
设置环境变量: export USE_BUILTIN_RIPGREP=0
永久设置: echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.profile
重新安装 Claude Code

Q4: 权限被拒绝错误

症状: 安装或运行时提示 "Permission denied"。

解决方法:

确保目录权限正确: mkdir -p ~/.local/bin && chmod 755 ~/.local/bin
确保文件有执行权限: chmod +x ~/.local/bin/claude
检查目录所有权: ls -la ~/.local/bin

Q5: WSL 性能问题

症状: Claude Code 运行缓慢。

解决方法:

确保使用 WSL 2: wsl -l -v（VERSION 应该是 2）
优化 WSL 2 内存配置（编辑 C:\Users\你的用户名\.wslconfig）
重启 WSL: wsl --shutdown
在 Linux 原生文件系统中工作（不要在 /mnt/c 下工作）

Q6: ARM64 架构问题

症状: 在树莓派或 ARM 服务器上安装失败。

解决方法:

确认架构: uname -m（应显示 aarch64 或 arm64）
手动下载 ARM64 版本
验证安装: file ~/.local/bin/claude

进阶配置

Shell 别名和函数

编辑 ~/.bashrc 或 ~/.zshrc：

                    # Claude Code 别名
alias cc='claude'
alias ccd='claude doctor'
alias ccu='claude update'

# 快速提问函数
ask() {
  claude "$@"
}

# 在特定目录运行 Claude Code
claude-project() {
  cd ~/Projects/$1 && claude
}
                

自动补全

Bash 自动补全:

                    # 生成补全脚本
claude --bash-completion > ~/.claude-completion.bash

# 加载补全
echo 'source ~/.claude-completion.bash' >> ~/.bashrc
source ~/.bashrc
                

Zsh 自动补全:

                    # 生成补全脚本
claude --zsh-completion > ~/.claude-completion.zsh

# 加载补全
echo 'source ~/.claude-completion.zsh' >> ~/.zshrc
source ~/.zshrc
                

Docker 容器中使用

Dockerfile 示例:

                    FROM ubuntu:22.04

# 安装基础工具
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 安装 Claude Code
RUN curl -fsSL https://claude.ai/install.sh | bash

# 配置环境变量
ENV PATH="/root/.local/bin:${PATH}"
ENV ANTHROPIC_API_KEY="your-api-key"

WORKDIR /workspace
CMD ["bash"]
                

更新 Claude Code

原生安装更新:

claude update

npm 更新:

npm update -g @anthropic-ai/claude-code

卸载 Claude Code

完全卸载:

                    # 删除二进制文件
rm ~/.local/bin/claude

# 删除配置文件
rm -rf ~/.claude

# 清理缓存
rm -rf ~/.cache/claude
                

总结

完成上述步骤后，你已经在 Linux/WSL2 系统上成功安装并配置了 Claude Code。

快速命令参考

                    claude                    # 启动交互式会话
claude "帮我写一个脚本"   # 直接提问
claude --version          # 查看版本
claude doctor             # 系统诊断
claude update             # 更新 Claude Code
claude --help             # 查看帮助
which claude              # 查看安装位置
                

Linux/WSL 特有优势:

轻量高效: Linux 系统资源占用少
完美的开发环境: 原生支持各种开发工具
WSL 互操作: 可同时访问 Windows 和 Linux 文件系统
服务器部署: 可在生产服务器上使用
Docker 友好: 可轻松容器化

WSL 2 特别优势:

完整的 Linux 内核
更快的文件系统性能
完全的系统调用兼容性
与 Windows 无缝集成

下一步建议:

阅读官方文档了解更多功能
在实际项目中使用 Claude Code
配置 Shell 别名提高效率
探索 Docker 和 CI/CD 集成
加入社区讨论最佳实践

Claude Code Linux/WSL2 系统完整安装指南

系统要求

最低配置

推荐配置

必需软件

Linux 发行版支持

Ubuntu / Debian 系列

Fedora / RHEL / CentOS 系列

Arch Linux 系列

Alpine Linux

其他发行版

WSL2 安装指南

安装前准备

系统要求与基础配置

判断电脑是否开启虚拟化

开启虚拟化功能（关键步骤！）

启用 Windows 功能

步骤 1: 在 Windows 上安装 WSL 2

检查 WSL 版本

全新安装 WSL 2 (Windows 10 2004+ 或 Windows 11)

从 WSL 1 升级到 WSL 2

步骤 2: 选择并安装 Linux 发行版

查看可用发行版

安装特定发行版

步骤 3: 首次设置 Ubuntu

启动 Ubuntu

创建用户名和密码

更新系统软件包

步骤 4: 在 WSL 中安装 Claude Code

方法一: 使用一键安装脚本（推荐）

方法二: 使用 npm 安装

步骤 5: WSL 特别配置

配置 WSL 2 内存限制

WSL 与 Windows 文件系统互操作

Linux 原生安装

方式一: 一键安装脚本（推荐）

步骤 1: 确保已安装 curl

步骤 2: 执行安装脚本

方式二: Alpine Linux 专用安装

步骤 1: 安装必需依赖

步骤 2: 设置环境变量

步骤 3: 运行安装脚本

方式三: 手动下载安装

步骤 1: 下载二进制文件

步骤 2: 安装到本地目录

方式四: 使用 Node.js/npm 安装

步骤 1: 安装 Node.js 环境

步骤 2: 安装 Claude Code

步骤 3: 验证安装

环境配置

配置 PATH 环境变量

自动配置（推荐）

手动配置 - Bash 用户

手动配置 - Zsh 用户

手动配置 - Fish 用户

系统级配置（所有用户）

API 配置

获取 API Key

官方 API

中转 API（国内推荐）

配置方式

Bash 用户配置

Zsh 用户配置

Fish 用户配置

验证配置

配置说明

验证安装

步骤 1: 打开新的终端

步骤 2: 检查版本

步骤 3: 检查安装位置

步骤 4: 系统诊断

步骤 5: 测试运行

常见问题

Q1: 提示 "command not found: claude"

Q2: WSL 中找不到 claude 命令

Q3: Alpine Linux 安装失败

Q4: 权限被拒绝错误

Q5: WSL 性能问题

Q6: ARM64 架构问题

进阶配置