Claude Code：安装与登录

时效说明：本文内容以 2026 年 3 月为基准。

2.1 前置条件：Node.js 18+

Claude Code 是一个 npm 包，所以你需要先装 Node.js。很多后端 Java 开发者不一定装了 Node，先检查一下：

bash

node --version

如果输出类似 v20.11.0 这样的版本号，说明已经有了。如果提示 "command not found"，需要先安装 Node.js。

Node.js 18 是最低要求，建议直接装最新的 LTS 版本（当前 LTS 版本请查看 nodejs.org）。

2.1.1 用版本管理工具安装 Node.js（推荐）

直接装一个固定版本的 Node.js 在未来可能会遇到版本冲突。比如项目 A 需要 Node 18，项目 B 需要 Node 20，两个版本没法同时装。推荐用版本管理工具，随时切换：

macOS/Linux 推荐：nvm（Node Version Manager）

bash

# 安装 nvm（会自动加到你的 .zshrc 或 .bashrc）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.zshrc   # 或者 source ~/.bashrc

# 验证 nvm 安装
nvm --version

# 安装最新的 LTS 版本
nvm install --lts

# 查看已安装的版本
nvm list

# 切换版本
nvm use 20

国内访问 nvm 安装脚本可能较慢，可以从镜像安装：

bash

# 设置 nvm 使用国内镜像下载 Node.js
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install --lts

更快的替代品：fnm（Fast Node Manager，Rust 编写）

fnm 比 nvm 启动快很多，如果你在意终端响应速度：

bash

# macOS（需要先装 Homebrew）
brew install fnm

# 把初始化脚本加到 .zshrc
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
source ~/.zshrc

# 安装 LTS 版本
fnm install --lts
fnm use lts-latest

Windows 推荐：nvm-windows

Windows 上的 nvm 是一个独立项目（不是同一个工具），从这里下载安装包：

code

https://github.com/coreybutler/nvm-windows/releases

下载 nvm-setup.exe 安装，然后：

powershell

# 在 PowerShell 中（以管理员身份运行）
nvm install lts
nvm use lts
node --version

2.1.2 直接从官网安装 Node.js

如果你不想用版本管理工具，也可以直接从官网下载安装包，简单粗暴：

macOS/Windows：去 nodejs.org 下载 LTS 版本的安装包，双击安装
Linux（Ubuntu/Debian）：

bash

# 使用 NodeSource 的源，安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

2.2 安装 Claude Code

2.2.1 npm 安装（推荐，国内首选）

直接用 npm 全局安装，这是最通用的方式：

bash

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

国内用户如果安装慢或者卡住，加上淘宝镜像源：

bash

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

也可以全局永久设置镜像（推荐，以后装其他包也快）：

bash

npm config set registry https://registry.npmmirror.com
# 之后直接安装
npm install -g @anthropic-ai/claude-code

安装完之后验证一下：

bash

claude --version
# 输出类似：2.1.x (Claude Code)

2.2.2 官方脚本安装

官方提供了一键安装脚本：

bash

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

注意：官方安装脚本需要访问 claude.ai，国内网络环境下通常无法访问。推荐直接使用上方的 npm 安装方式。

2.3 Windows 安装详细步骤

Windows 用户有两种路线，下面分别详述。

2.3.1 方式一：WSL2（推荐，体验最佳）

WSL2（Windows Subsystem for Linux 2）让你在 Windows 上运行一个真正的 Linux 环境。Claude Code 在 WSL2 里跑得非常好，跟在 macOS/Linux 上一模一样。如果你平时做后端开发，WSL2 是很值得装的。

第一步：启用 WSL2

以管理员身份打开 PowerShell 或者命令提示符：

powershell

# 安装 WSL2（Windows 10 2004+ 或 Windows 11 都支持）
wsl --install

# 安装完之后重启电脑

重启后会自动打开 Ubuntu 的安装界面，按提示设置用户名和密码。

第二步：在 WSL2 里安装 Node.js

打开 Ubuntu 终端：

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# 安装 Node.js LTS
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install --lts

# 验证
node --version
npm --version

第三步：安装 Claude Code

bash

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
claude --version

第四步：在 WSL2 里访问 Windows 的项目文件

你的 Windows 盘挂载在 /mnt/ 下：

bash

# C 盘在 /mnt/c，D 盘在 /mnt/d
ls /mnt/c/Users/你的用户名/workspace

# 直接进入 Windows 里的项目目录启动 Claude Code
cd /mnt/c/Users/你的用户名/workspace/my-spring-boot-project
claude

推荐配合 Windows Terminal + VS Code Remote WSL 使用，体验会更好。VS Code 安装 "Remote - WSL" 扩展后，可以在 WSL 环境里打开项目，无缝使用。

2.3.2 方式二：原生 PowerShell 安装

如果你不想装 WSL2，也可以在 Windows 原生环境里跑 Claude Code。

第一步：安装 Node.js

从 nodejs.org 下载 LTS 版本的 Windows 安装包（.msi 格式），双击安装，全部默认选项即可。

验证：

powershell

node --version
npm --version

第二步：安装 Claude Code

以管理员身份打开 PowerShell（右键点击 PowerShell 图标，选"以管理员身份运行"）：

powershell

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

第三步：处理 PowerShell 执行策略问题

Windows 默认可能禁止执行脚本，如果遇到 "因为在此系统上禁止运行脚本" 的错误：

powershell

# 允许运行本地脚本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

第四步：验证

powershell

claude --version

Windows 原生的局限： Claude Code 在 Windows 原生环境下部分功能可能表现不如 WSL2，尤其是涉及 shell 脚本执行的场景。如果你的项目用了大量 shell 脚本或者 Unix 风格的工具链，还是推荐 WSL2。

2.4 常见安装问题排查

2.4.1 permission denied（macOS/Linux）

这是 macOS/Linux 上最常见的问题，原因是 npm 全局目录权限不够。不建议用 sudo npm install，这会污染文件权限。更好的解决方式是让 npm 全局目录放到用户 home 下：

bash

# 创建用户级别的 npm 目录
mkdir ~/.npm-global

# 配置 npm 使用这个目录
npm config set prefix '~/.npm-global'

# 把这个目录加到 PATH（加到你的 .zshrc 或 .bash_profile 里）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 然后重新安装（不需要 sudo）
npm install -g @anthropic-ai/claude-code

如果你用的是 nvm 或者 fnm 管理的 Node.js，通常不会有权限问题，因为 Node.js 就装在用户目录下。

2.4.2 安装很慢，长时间无响应

国内直连 npm 官方镜像慢很正常，加上镜像源：

bash

# 临时指定
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 永久设置
npm config set registry https://registry.npmmirror.com

如果加了镜像还是慢，检查是否有代理设置影响了 npm：

bash

# 查看当前 npm 代理设置
npm config get proxy
npm config get https-proxy

# 如果有代理但不需要，清除它
npm config delete proxy
npm config delete https-proxy

2.4.3 Python 相关的依赖报错

某些版本的 npm 包安装时需要编译原生模块，会用到 Python 和 C++ 编译器。如果你遇到类似这样的错误：

code

gyp ERR! find Python
gyp ERR! No acceptable Python interpreter found

macOS：安装 Xcode 命令行工具，它包含了编译器和 Python：

bash

xcode-select --install

Windows：安装 Windows Build Tools：

powershell

# 以管理员身份运行 PowerShell
npm install --global --production windows-build-tools

或者安装 Visual Studio Build Tools（选择 "C++ 生成工具" 组件）。

Linux：

bash

sudo apt-get install -y build-essential python3

2.4.4 网络超时，下载中断

如果网络不稳定，安装中途可能超时失败。可以设置更长的超时时间：

bash

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com --timeout=60000

或者设置全局超时：

bash

npm config set timeout 60000

2.4.5 Node.js 版本不够

如果你系统上已经有 Node.js，但版本太旧（低于 18），直接安装会报错。先更新 Node.js：

bash

# 用 nvm 更新
nvm install --lts
nvm use --lts

# 验证版本
node --version  # 应该是 18.x 或更高

2.4.6 WSL2 中 claude 命令找不到

在 WSL2 里安装成功但 claude 命令找不到，通常是 PATH 没配好：

bash

# 查看 npm 全局目录
npm config get prefix
# 输出类似：/home/你的用户名/.nvm/versions/node/v20.11.0

# 确认 bin 目录在 PATH 里
echo $PATH | grep -o '[^:]*npm[^:]*' || echo "npm bin 不在 PATH 里"

# 临时加入 PATH（永久的话写入 .bashrc）
export PATH="$(npm config get prefix)/bin:$PATH"

2.5 登录方式详解

安装完之后，进入任意目录，运行 claude，首次启动会引导你登录。

2.5.1 方式一：Claude 订阅账号（Pro/Max/Teams）

如果你有 Claude 的付费订阅，可以直接用账号登录。Claude Code 的用量包含在订阅额度里，不额外计费。

套餐区别：

Pro：适合个人开发者日常使用，有每月使用量限制，超出后会降速或需要等下月
Max（5x/20x）：专门为 Claude Code 等高用量场景设计，限制更宽松，适合重度用户（价格以官方页面为准）
Teams：适合团队共享，可以统一管理账号和用量

在 Claude Code 的交互界面里输入：

code

/login

然后按提示，会打开浏览器完成 OAuth 授权，完成后回到终端就登录好了。

登录状态是持久的，不需要每次重新登录，除非你主动退出（/logout）或者 token 过期。

2.5.2 方式二：Console API Key（按量计费）

如果你没有 Claude 订阅，或者你想精确控制费用（按实际 token 用量计费），可以用 API Key 方式。

获取 API Key 的步骤：

访问 console.anthropic.com（需要能访问的网络）
注册并登录账号
进入 "API Keys" 页面
点击 "Create Key"，给 Key 起个名字（比如 "claude-code-local"）
复制生成的 Key（以 sk-ant- 开头），注意：这是唯一一次显示完整 Key 的机会

把 API Key 配置为环境变量：

bash

export ANTHROPIC_API_KEY=sk-ant-你的API_Key

或者写到 shell 配置文件里永久生效：

bash

echo 'export ANTHROPIC_API_KEY=sk-ant-你的API_Key' >> ~/.zshrc
source ~/.zshrc

然后直接运行 claude，它会自动使用环境变量里的 Key，不会弹出登录界面。

2.5.3 方式三：第三方兼容 API（国内推荐）

如果你想用国内的 API 服务（比如 DeepSeek）代替官方 Claude，这属于 API Key 方式的变体，具体配置在下一章详细讲。

2.6 第一次启动看到什么

登录之后，在任意项目目录运行 claude，你会看到类似这样的欢迎界面：

code

╭─────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!               │
│                                         │
│   /help for help, /status to check      │
│   your connection                       │
╰─────────────────────────────────────────╯

✔ Logged in as: your@email.com

> _

底部的 > 是输入提示符，你可以直接用中文输入任务。

几个常用的斜杠命令：

命令	说明
`/help`	查看所有可用命令
`/status`	检查连接状态和当前使用的模型
`/clear`	清除当前对话的上下文，开始新对话
`/compact`	压缩对话历史（节省 token）
`/login`	切换或重新登录账号
`/logout`	退出登录
`/model`	查看或切换当前使用的模型

2.7 验证安装成功的完整检查清单

安装完之后，按这个清单确认一切正常：

bash

# 1. 确认 Node.js 版本 >= 18
node --version
# 期望输出：v18.x.x 或更高

# 2. 确认 npm 可用
npm --version
# 期望输出：任意版本号

# 3. 确认 claude 命令可用
claude --version
# 期望输出：2.x.x (Claude Code)

# 4. 确认 claude 命令路径正常（命令找不到时用这个排查）
which claude
# macOS/Linux 期望输出：/Users/你的用户名/.npm-global/bin/claude 之类的路径

然后进入一个项目目录，启动 Claude Code：

bash

cd /path/to/any/project
claude

在交互界面里输入 /status，确认：

code

● Claude Code Status
  Model:    claude-opus-4-5 (或你配置的模型)
  Auth:     Logged in as your@email.com (或 API Key configured)
  Version:  2.x.x

如果 Model 和 Auth 都正常显示，说明安装和登录都成功了。

2.8 更新 Claude Code 版本

Claude Code 更新频率较高，建议定期更新。更新方式很简单：

bash

# 更新到最新版本
npm update -g @anthropic-ai/claude-code

# 或者重新安装（效果相同）
npm install -g @anthropic-ai/claude-code

# 使用国内镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 确认更新成功
claude --version

Claude Code 自身也有检查更新的提示，启动时如果有新版本会主动告诉你。

关于更新频率的建议： Claude Code 的更新通常包含 bug 修复和性能改善，不建议一直用旧版本。但也没必要每天更新，大概每周或者每次遇到问题时更新一下就可以了。如果某次更新后出现了奇怪的问题，可以回退到之前的版本：

bash

# 安装指定版本（如果新版本有问题）
npm install -g @anthropic-ai/claude-code@2.0.0

# 查看可用版本列表
npm view @anthropic-ai/claude-code versions