---
作者：Caelum | 2026-06-10
> 本文提供在 Arch Linux 上安装 Claude Code CLI 的完整方案，涵盖直连安装、代理配置、常见问题排查，以及 CC Switch 快速切换 API 端点工具。建议收藏备用！
---
一、环境准备
在开始之前，请确认你的 Arch Linux 系统已安装以下基础工具：
1. 安装 Node.js 与 npm
Claude Code 需要 Node.js 18+ 环境。推荐使用 `nvm` 管理版本：
```bash
# 安装 nvm（Node Version Manager）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重新加载 shell 配置
source ~/.bashrc # 或 source ~/.zshrc
# 安装 Node.js LTS
nvm install --lts
nvm use --lts
# 验证
node -v # 应显示 v20.x 或 v22.x
npm -v
```
> 💡 提示：也可以直接用 pacman 安装，但版本可能偏旧：
```bash
> sudo pacman -S nodejs npm
> ```
2. 安装其他依赖
```bash
sudo pacman -S git unzip
```
> ⚠️ 建议：先运行 `sudo pacman -Syu` 更新系统，避免依赖冲突。
---
二、安装方式
方式一：无代理安装（直连）
适用于服务器在海外、或网络可直接访问 `registry.npmjs.org` 的场景。
```bash
npm install -g @anthropic-ai/claude-code
```
npm 下载速度慢？ 切换国内镜像源：
```bash
# 设置为淘宝镜像（npmmirror）
npm config set registry https://registry.npmmirror.com
# 验证
npm config get registry
# 再执行安装
npm install -g @anthropic-ai/claude-code
```
> ⚠️ 注意：npm 镜像源有时同步滞后，如果找不到最新版，请临时切回官方源：
```bash
> npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org
> ```
---
方式二：代理安装（国内环境推荐）
HTTP 代理配置
```bash
# 配置 npm 代理（请替换为你的实际代理地址）
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
# 同时设置终端代理
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
# 持久化写入 shell 配置
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc
source ~/.bashrc
```
执行安装：
```bash
npm install -g @anthropic-ai/claude-code
```
安装后清除代理（如需恢复直连）：
```bash
npm config delete proxy
npm config delete https-proxy
unset http_proxy https_proxy
```
---
SOCKS5 代理配置
方法一：使用 proxychains-ng
```bash
# 安装
sudo pacman -S proxychains-ng
# 编辑配置
sudo nano /etc/proxychains.conf
# 在文件末尾添加：
# socks5 127.0.0.1 1080
# 通过 proxychains 运行 npm
proxychains npm install -g @anthropic-ai/claude-code
```
方法二：使用 tsocks
```bash
# 通过 AUR 安装
yay -S tsocks
# 配置 /etc/tsocks.conf
# server = 127.0.0.1
# server_port = 1080
# server_type = 5
# 使用
tsocks npm install -g @anthropic-ai/claude-code
```
---
配合 Clash Verge / Mihomo Party
```bash
# 安装 Mihomo Party（推荐通过 AUR）
yay -S mihomo-party-bin
# 开启系统代理后，终端设置环境变量
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
# 直接安装
npm install -g @anthropic-ai/claude-code
```
---
三、安装后验证与配置
验证安装
```bash
claude --version
```
预期输出：`@anthropic-ai/claude-code v2.x.x`
首次登录
```bash
claude login
```
浏览器会自动打开 Anthropic 登录页面。如果浏览器无法自动打开，终端会打印一个 URL，手动复制到浏览器完成认证即可。
配置 API 端点（使用代理 API）
```bash
# 设置自定义 API Base URL
export ANTHROPIC_BASE_URL=https://your-api-proxy.com
# 设置 API Key（跳过 login 方式）
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# 持久化
echo 'export ANTHROPIC_BASE_URL=https://your-api-proxy.com' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc
```
---
四、CC Switch — API 端点一键切换
[CC Switch](https://github.com/sky2233/cc-switch) 是一款开源的 Claude Code API 端点快速切换工具，支持在官方 / OpenRouter / 自定义代理之间一键切换。
核心功能
✅ 管理多组 API Key + Base URL 配置
✅ 一键切换，无需手动改环境变量
✅ 支持备份与还原
✅ 交互式 TUI 界面
安装方式（三选一）
方式 A：直接下载二进制（推荐）
```bash
wget https://github.com/sky2233/cc-switch/releases/latest/download/cc-switch-linux-amd64 -O cc-switch
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/
```
方式 B：npm 安装
```bash
npm install -g cc-switch
```
方式 C：源码编译（需 Go 环境）
```bash
git clone https://github.com/sky2233/cc-switch.git
cd cc-switch
go build -o cc-switch .
sudo mv cc-switch /usr/local/bin/
```
常用命令
```bash
# 启动交互界面
cc-switch
# 添加配置
cc-switch add official
# 交互式输入：Name → API Key → Base URL → Default Model
# 切换配置
cc-switch use official
# 列出所有配置
cc-switch list
# 备份
cc-switch backup
# 查看帮助
cc-switch --help
```
典型配置示例
配置名称 API Key Base URL Model
official `sk-ant-api03-xxx` `https://api.anthropic.com` `claude-sonnet-4-6`
openrouter `sk-or-v1-xxx` `https://openrouter.ai/api` `anthropic/claude-sonnet-4-6`
my-proxy `sk-xxx` `https://my-proxy.example.com` `claude-sonnet-4-6`
> 💡 提示：切换配置后，直接运行 `claude` 即可使用新端点，无需重新登录。
---
五、常见问题速查
❌ Q1: npm install 报 ECONNREFUSED / ETIMEDOUT
原因：网络无法连接 `registry.npmjs.org`
解决：
1. 确认代理已正确设置：`curl -x http://127.0.0.1:7890 https://registry.npmjs.org`
2. 检查 `npm config list` 确认 proxy 配置生效
3. 用 proxychains 包装安装命令
4. 换用国内镜像源
---
❌ Q2: claude 命令找不到 (command not found)
原因：npm 全局 bin 目录不在 PATH 中
解决：
```bash
# 查看 npm 全局 bin 路径
npm config get prefix
# 添加到 PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 如果用 nvm，确认初始化配置存在
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
```
---
❌ Q3: Permission denied (EACCES) 安装报错
解决：
```bash
# 方案 A：修改 npm 全局目录到用户目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 方案 B：使用 sudo（不推荐但最快）
sudo npm install -g @anthropic-ai/claude-code
```
---
❌ Q4: 代理设置后 npm 仍然不走代理
解决：
1. 确认代理端口正确：`netstat -tlnp | grep 7890`
2. 测试连通性：`curl -v --proxy http://127.0.0.1:7890 https://www.google.com`
3. npm 需显式设置 `npm config set proxy`，不遵守 `http_proxy` 环境变量
4. npm 不支持 SOCKS5，必须用 proxychains 或转为 HTTP 代理
---
❌ Q5: claude login 后浏览器不打开 / 认证失败
解决：
- 手动复制终端打印的 URL 到浏览器
- 跳过 login，改用 API Key 方式设置 `ANTHROPIC_API_KEY`
- 安装 xdg-utils：`sudo pacman -S xdg-utils`
---
❌ Q6: CC Switch 切换后 claude 仍用旧配置
解决：
```bash
# 检查当前配置
cc-switch list
# 确认环境变量未被覆盖
env | grep ANTHROPIC
# 清除冲突的环境变量
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
# 从 shell 配置文件中移除旧的 export 语句
```
---
❌ Q7: npm 报证书错误 (UNABLE_TO_VERIFY_LEAF_SIGNATURE)
解决：
```bash
# 临时绕过（企业代理环境可能需要）
npm config set strict-ssl false
# 安装完成后恢复
npm config set strict-ssl true
```
---
六、卸载 Claude Code
```bash
# 卸载 npm 包
npm uninstall -g @anthropic-ai/claude-code
# 清理配置目录（会删除所有配置和对话历史）
rm -rf ~/.claude
# 清理 npm 缓存
npm cache clean --force
# 卸载 CC Switch
npm uninstall -g cc-switch
# 或删除二进制
sudo rm /usr/local/bin/cc-switch
```
---
写在最后
以上就是 Arch Linux 安装 Claude Code 的完整方案。如果你在安装过程中遇到其他问题，欢迎在评论区留言交流！
> 📌 在线预览版：[https://archlinux-claudecode.vercel.app/]
🔧 CC Switch 项目：[https://github.com/sky2233/cc-switch]
---
本文最后更新于 2026-06-10
---
