前言

Claude Code 是 Anthropic 推出的命令行 AI 编程工具，代码理解和多文件编辑能力较强。国内开发者上手时通常会遇到两个问题：一是 Node.js 环境和 npm 全局安装的权限/路径坑，二是 API 的网络连通性与计费方式。本文梳理一套可复现的安装流程，并说明几种 API 接入方式的差异，供大家按需选择。

一、环境要求

Claude Code 支持的系统：

• macOS 10.15+
• Linux（Ubuntu 18.04+、Debian 10+、CentOS 7+）
• Windows 10/11（建议通过 WSL2 运行）

二、安装 Node.js

Claude Code 基于 Node.js，建议 18 或更高版本。

macOS / Linux（推荐用 nvm 管理版本）：

# 安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置

source ~/.zshrc # 或 source ~/.bashrc

# 安装并切换到 Node.js 20

nvm install 20

nvm use 20

# 验证

node --version # v20.x.x

npm --version

Windows： 在应用商店安装 Ubuntu（WSL2），在 Ubuntu 终端里执行上面的 Linux 命令即可。WSL2 下的体验比原生 PowerShell 更稳定，路径和编码问题更少。

npm 安装慢的话，可切换到国内镜像：

npm config set registry https://registry.npmmirror.com

三、安装 Claude Code

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

claude --version # 验证

如果在 macOS/Linux 上遇到全局安装权限错误，不建议直接 sudo（会让全局目录归属 root，后续更新更麻烦）。更干净的做法是把 npm 全局目录指到用户目录：

mkdir ~/.npm-global

npm config set prefix '~/.npm-global'

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

source ~/.zshrc

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

四、配置 API

Claude Code 通过两个环境变量识别接入方式：

• ANTHROPIC_API_KEY：密钥
• ANTHROPIC_BASE_URL：API 地址（不设置时默认走 Anthropic 官方）

注意：变量名是 ANTHROPIC_BASE_URL，不是 BASE_URL，写错会导致请求仍发往默认地址。

接入方式对比

方式	适用场景	说明
Anthropic 官方	有海外信用卡、网络可直连	直接配置 ANTHROPIC_API_KEY 即可，无需改 Base URL
第三方 API 中转	不便使用官方计费/网络	需同时配置 Key 和 Base URL，地址以服务商提供的为准

如果选择第三方中转服务，选型时建议关注：是否稳定、计费是否透明、数据是否经过你不希望经过的环节。市面上有多家服务商，本文不做特定推荐，请自行评估后再接入。

配置环境变量（推荐）

macOS / Linux：

# 编辑对应 shell 的配置文件

nano ~/.zshrc # zsh

# 或 nano ~/.bashrc # bash

# 追加（用官方就只配第一行；用中转再配第二行）

export ANTHROPIC_API_KEY="你的密钥"

export ANTHROPIC_BASE_URL="https://api.highwayapi.ai/openai"

source ~/.zshrc

Windows PowerShell（原生）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "你的密钥", "User")

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://你的服务商地址", "User")

项目级配置

也可以在项目根目录放 .env，但务必加入 .gitignore，避免密钥泄露到仓库：

ANTHROPIC_API_KEY=你的密钥

ANTHROPIC_BASE_URL=https://你的服务商地址

五、验证安装

claude "用 Python 写一个读取 CSV 文件的函数"

正常会返回模型生成的代码。若报错，见下一节排查。

六、常见问题排查

1. command not found: claude
npm 全局目录不在 PATH 中：

npm root -g # 查看全局目录

echo 'export PATH="$(npm root -g)/../bin:$PATH"' >> ~/.zshrc

source ~/.zshrc

2. 401 Unauthorized
Key 错误或 Base URL 配置有误。检查环境变量、确认没有多余空格或引号：

echo $ANTHROPIC_API_KEY

echo $ANTHROPIC_BASE_URL

3. 连接超时
网络问题或地址填错。可用 curl 直接测试 Base URL 是否可达（把地址换成你实际使用的）：

curl -sS https://你的服务商地址/v1/models \

-H "Authorization: Bearer 你的密钥"

curl 也超时，说明是网络或地址问题，而非 Claude Code 本身。

4. Windows 终端中文乱码
PowerShell 执行 chcp 65001 切到 UTF-8，或改用 WSL2 终端。

七、基础使用

进入项目目录：

cd my-project

claude

常用命令：

• claude "任务描述" — 单次执行
• claude — 进入交互模式
• /help — 查看全部命令
• /compact — 压缩上下文，节省 token
• /clear — 清空对话历史
• Ctrl+C — 中断当前任务

小结

国内用 Claude Code 的关键点就两个：把 Node.js 环境和 npm 全局路径理顺，以及根据自己的网络和付费情况选择合适的 API 接入方式。官方直连和第三方中转各有适用场景，按需选择即可。配置过程中遇到的问题，绝大多数都能在第六节的排查清单里找到对应解法。