Claude Code 是 Anthropic 官方推出的命令行AI编程Agent，支持代码生成、跨文件重构、Bug调试、项目迁移、终端自动化执行，是目前综合能力最强的编程AI工具之一。本文提供 Windows / Mac / Linux 全平台从零安装、环境配置、授权登录、基础使用、报错排查完整流程。

一、前置必备环境（全平台通用）

Claude Code 基于 Node.js 运行，所有系统必须满足以下条件：

  • Node.js 版本：≥18.x，推荐 20.x LTS（最稳定、兼容无报错）

  • 必备工具：Git（用于项目识别、文件追踪）

  • 运行环境：CMD / PowerShell / Terminal / Zsh 任意终端

二、分系统安装步骤

1、Windows 系统安装（Win10/Win11）

步骤1：安装 Node.js

方式1（推荐一键安装），管理员打开 PowerShell 执行：

winget install OpenJS.NodeJS.LTS

方式2：官网下载：https://nodejs.org/，选择 LTS 版本默认安装即可。

验证安装（必须新开终端）：

node --version
npm --version

步骤2：全局安装 Claude Code

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

步骤3：验证是否安装成功

claude --version

输出版本号（如 1.0.5x）即安装完成。

步骤4：环境变量修复（命令不识别必看）

若提示 claude 不是内部命令，手动添加环境变量：

路径：C:\Users\你的用户名\.local\bin

操作：系统属性 → 环境变量 → 用户变量 Path → 新建 → 粘贴上述路径 → 保存重启终端。

2、MacOS 系统安装

步骤1：安装依赖环境

# 安装命令行工具
sudo xcode-select --install

# 安装Homebrew（无则执行）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js LTS
brew install node

步骤2：安装 Claude Code

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

也可使用官方一键脚本：

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

步骤3：验证

claude --version

3、Linux / WSL 安装

# CentOS / Rocky
sudo dnf install -y nodejs git

# Ubuntu / Debian
sudo apt install nodejs npm git -y

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

三、授权登录配置（核心步骤）

1、官方登录方式（海外网络环境）

任意项目文件夹打开终端，执行：

claude

根据提示按回车跳转浏览器，登录 Anthropic 账号，授权后即可使用。

2、国内环境配置（无外网可用｜进阶配置）

国内无法直接跳转授权，可通过环境变量配置代理API实现使用，终端执行以下配置（根据自己shell选择）：

Bash 用户

echo 'export ANTHROPIC_BASE_URL="你的代理地址"' >> ~/.bash_profile
echo 'export ANTHROPIC_AUTH_TOKEN="你的APIKEY"' >> ~/.bash_profile
source ~/.bash_profile

Zsh 用户（Mac 默认）

echo 'export ANTHROPIC_BASE_URL="你的代理地址"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的APIKEY"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

$env:ANTHROPIC_BASE_URL="代理地址"
$env:ANTHROPIC_AUTH_TOKEN="APIKEY"

四、基础使用方法

1、进入AI编程交互模式

在任意项目根目录执行：

claude

进入对话窗口后，可直接输入自然语言指令：

  • 重构整个项目代码

  • 修复当前所有报错

  • 优化代码性能、规范代码格式

  • 新增接口、自动写单元测试

2、常用命令

# 查看版本
claude --version

# 查看帮助
claude --help

# 单次指令执行（不进入交互）
claude -p "帮我优化当前js代码"

五、常见报错与解决方案（高频避坑）

1、'claude' 不是内部或外部命令

原因：环境变量未生效

解决：添加 .local/bin 到系统PATH，重启终端或重启电脑。

2、Node版本过低报错

原因：低于18.x

解决：卸载旧版本，重装 Node 20.x LTS。

3、npm全局安装权限不足

Windows：以管理员身份运行终端再安装

Mac/Linux：添加 sudo 执行安装命令

4、登录跳转失败/无法授权

原因：国内网络限制

解决：使用上文环境变量配置代理API方式。

5、识别不到项目文件

解决：必须在项目根目录执行 claude 命令，且保证项目包含 Git 环境。

六、最佳使用建议

  1. 优先使用Node 20 LTS，兼容性最稳，几乎无报错

  2. 日常开发直接在项目根目录运行 claude，支持全文件扫描、跨文件重构

  3. 敏感项目建议本地使用，不上传云端，保证代码安全

  4. 固定开发场景可搭配自定义指令，固化编码规范、注释风格、代码格式