Claude Code 从零安装教程

0. Claude Code 是什么

Claude Code 是 Anthropic 官方出品的 AI 编程助手，直接在你的终端（命令行）里运行。

和 Codex App 的区别

工具	运行方式	适合谁	特点
Codex App	桌面 App，图形界面	不熟悉命令行的用户	点击操作，可视化强
Claude Code	终端命令行	开发者、喜欢命令行的用户	更灵活，可集成到工作流

这篇教程专注 Claude Code CLI。如果你更喜欢图形界面，可以看 Codex App 入门教程。

1. 安装前提：Node.js

Claude Code 需要 Node.js 18 或更高版本。

1.1 检查是否已安装

打开终端，运行：

node --version
npm --version

如果看到 v18.x.x 或更高，跳到第 2 步。

1.2 macOS 安装 Node.js

方法一（推荐）：从官网下载安装包

打开 nodejs.org
点击 "LTS" 版本下载
打开 .pkg 安装包，按向导安装
安装完成后打开终端，运行 node --version 验证

方法二：用 Homebrew（已有 Homebrew 的用户）

brew install node

1.3 Windows 安装 Node.js

打开 nodejs.org
下载 Windows Installer (.msi) LTS 版本
运行安装包，全部默认选项
安装完成后打开"命令提示符"或"PowerShell"
运行 node --version 验证

安装 Node.js 时勾选"Add to PATH"选项，否则终端找不到 node 命令。Windows 安装包默认已勾选，不要取消。

2. 安装 Claude Code

2.1 运行安装命令

打开终端（macOS：Spotlight 搜索"终端"；Windows：搜索"PowerShell"），运行：

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

-g 表示全局安装，安装一次，任何目录都能用。

2.2 验证安装

claude --version

看到版本号就说明安装成功。

如果 macOS 提示权限错误（EACCES），不要用 sudo npm install。正确做法是修复 npm 权限，或者用 nvm 管理 Node.js 版本。

2.3 macOS 权限问题处理

如果遇到权限错误，推荐用 nvm：

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

然后重启终端，再运行：

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

3. 首次登录与配置

有两种方式完成认证：浏览器登录或 API Key。

3.1 方式一：浏览器登录（推荐新手）

在终端运行 claude
首次运行会提示登录
按提示在浏览器中完成 Anthropic 账号授权
授权完成后回到终端，登录状态自动保存

需要有 Anthropic 账号。没有的话先去 anthropic.com 注册。

3.2 方式二：API Key（适合开发者）

如果你有 Anthropic API Key，可以设置环境变量：

macOS/Linux（临时，当前终端有效）：

export ANTHROPIC_API_KEY=your_key_here

macOS 永久设置（写入 ~/.zshrc）：

echo 'export ANTHROPIC_API_KEY=your_key_here' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell（当前会话）：

$env:ANTHROPIC_API_KEY="your_key_here"

API Key 不要写进代码文件、截图、群聊或任何公开地方。泄露后立即在 Anthropic 控制台撤销。

4. 第一次使用

4.1 进入你的项目目录

cd /path/to/your/project

macOS 示例：cd ~/Documents/my-project

Windows 示例：cd C:\Users\你的用户名\Documents\my-project

4.2 启动 Claude Code

claude

进入交互模式后，你会看到提示符，可以开始输入问题。

4.3 第一个对话示例

> 请列出这个项目里有哪些文件，并简单说明每个文件的作用

Claude Code 会读取当前目录，给出文件列表和说明。

Claude Code 只能读取你当前所在目录及其子目录的文件。进入项目目录再启动，它才能看到你的代码。

5. 常用命令速查

命令	说明	示例
`claude`	进入交互模式	直接运行，开始对话
`claude "问题"`	单次提问，不进入交互模式	`claude "这段代码有什么问题"`
`claude --help`	查看所有可用选项	—
`claude --version`	查看当前版本	—
`claude --model`	指定使用的模型	`claude --model claude-opus-4-5`
`/exit` 或 Ctrl+C	退出交互模式	在交互模式中输入
`/help`	查看交互模式内的帮助	在交互模式中输入
`/clear`	清除当前对话上下文	在交互模式中输入

6. 配置 CLAUDE.md

CLAUDE.md 是放在项目根目录的说明文件，告诉 Claude Code 这个项目的背景、规则和偏好。

6.1 为什么需要 CLAUDE.md

不用每次都重复解释项目背景
可以设定代码风格、禁止操作、输出格式
Claude Code 每次启动都会自动读取

6.2 基础模板

CLAUDE.md 基础模板

# 项目说明

## 这是什么项目
[用一两句话描述你的项目]

## 技术栈
[列出主要语言、框架、工具]

## 代码规范
- [你的代码风格要求]
- [命名规范]

## 注意事项
- 修改文件前先说明要做什么
- 不要删除注释
- [其他你认为重要的规则]

CLAUDE.md 越具体越好。写清楚"不要做什么"比写"要做什么"更重要。

7. 常见问题排错

7.1 command not found: claude

原因：安装没成功，或 PATH 没配置好。

处理：重新运行 npm install -g @anthropic-ai/claude-code，然后重启终端。

7.2 401 Unauthorized

原因：API Key 无效、过期或没有设置。

处理：检查 ANTHROPIC_API_KEY 环境变量是否正确设置，或重新登录。

7.3 网络连接失败

原因：网络问题或需要代理。

处理：确认网络能访问 anthropic.com。如需代理，设置 HTTPS_PROXY 环境变量。

7.4 Claude Code 看不到我的文件

原因：没有在项目目录下启动。

处理：先 cd 进入项目目录，再运行 claude。

7.5 macOS 提示"无法验证开发者"

原因：macOS Gatekeeper 安全限制。

处理：这个问题不适用于 npm 安装的工具。如果是下载的二进制文件，在"系统设置 → 隐私与安全性"中允许运行。