Claude Code 安装使用文档

一个跑在终端里的 AI 编程助手，不是插件，是独立工具

这东西是什么

Claude Code 是 Anthropic 出的一个命令行工具，直接在终端里跟 Claude 对话，让它帮你写代码、改代码、调试、跑命令。

跟 Cursor、Copilot 那些不太一样——它不依赖 IDE，不需要 VS Code 或 JetBrains，打开终端就能用。

适合已经在用命令行工作的人，也适合不想被 IDE 插件绑住的人。

安装前准备

系统要求

• • Node.js 18+（必须是 18 或以上，低版本不行）
• • 操作系统：macOS、Linux、Windows（Windows 需要 WSL2 或原生支持）
• • 网络：需要能访问 Anthropic API

检查 Node.js 版本

node --version

如果没装或者版本不对，去 nodejs.org 下载 LTS 版本安装。

或者用 nvm 管理：

macOS/Linux：

# 安装 nvm（如果还没装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 安装 Node.js 18
nvm install 18
nvm use 18

Windows：

用 nvm-windows，去 GitHub 下载 nvm-setup.exe 安装，然后：

nvm install 18
nvm use 18        # 需要管理员权限运行终端

安装 Claude Code

方法一：npm 全局安装（推荐）

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

装完之后检查一下：

claude --version

能输出版本号就说明装好了。

方法二：如果 npm 装不上

有时候网络问题或者权限问题会导致装不上，可以试试：

# macOS/Linux
sudo npm install -g @anthropic-ai/claude-code

# 或者换个 npm 源
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

Windows 用户如果在 WSL 里，按上面来就行。如果直接在 Windows 命令行里，可能需要用管理员权限运行。

登录和认证

Claude Code 有多种认证方式，下面从简单到复杂依次介绍。

方式一：官方账号登录

claude login

会打开浏览器，登录 Anthropic 账号授权。

这种方式使用的是 Claude Pro/Team 订阅额度，或者按量付费。

方式二：环境变量 + 配置文件（免登录，推荐国内用户）

如果你用的是国内云服务商的 AI 接口（比如阿里云百炼、腾讯云等），不需要走 claude login，直接配置环境变量就行。

在项目根目录创建 .claude/settings.json：

{
"env":{
"ANTHROPIC_AUTH_TOKEN":"你的 API Token",
"ANTHROPIC_BASE_URL":"你的服务商 API 地址",
"ANTHROPIC_MODEL":"",
"ANTHROPIC_DEFAULT_SONNET_MODEL":"qwen3.6-max-preview",
"ANTHROPIC_DEFAULT_OPUS_MODEL":"kimi-k2.6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL":"qwen3.6-27b",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":"1"
},
"model":"sonnet"
}

各字段说明：

关于 sonnet / opus / haiku：
这是 Anthropic 的三个 Claude 模型档位。Sonnet 是平衡型，Opus 最强但最贵最慢，Haiku 最快最便宜。在使用国内云服务商时，这些名称只是”档位标识”，实际跑的是你映射的具体模型。比如配置里 sonnet 映射到 qwen3.6-max-preview，当你输入 /model sonnet 时，实际调用的是 qwen 模型，不是 Anthropic 的 Sonnet。

配置好之后，直接运行 claude 就能用了，不需要登录。

注意：ANTHROPIC_AUTH_TOKEN 不要提交到 Git 里。可以在项目里加一个 .gitignore，把 .claude/settings.json 排除掉。

方式三：全局配置文件（免登录，适合所有项目通用）

如果不想每个项目都配一遍 .claude/settings.json，可以直接改全局配置文件 ~/.claude/settings.json，对所有项目生效。

Windows 用户路径：C:\Users\你的用户名\.claude\settings.json

{
"env":{
"ANTHROPIC_AUTH_TOKEN":"你的 API Token",
"ANTHROPIC_BASE_URL":"你的服务商 API 地址",
"ANTHROPIC_DEFAULT_SONNET_MODEL":"qwen3.6-max-preview",
"ANTHROPIC_DEFAULT_OPUS_MODEL":"kimi-k2.6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL":"qwen3.6-27b",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":"1"
},
"model":"sonnet"
}

或者用命令直接写进去，不用手动编辑文件：

claude config set ANTHROPIC_AUTH_TOKEN "你的 API Token"
claude config set ANTHROPIC_BASE_URL "你的服务商 API 地址"
claude config set model sonnet

这种方式的好处是配一次就行，不管切到哪个项目目录都能直接用。

如果项目目录里也有 .claude/settings.json，项目配置会覆盖全局配置。

方式四：纯环境变量

也可以不写配置文件，纯用环境变量：

export ANTHROPIC_API_KEY=your-api-key-here

加到 ~/.bashrc 或 ~/.zshrc 里，每次打开终端自动生效。

不过这种方式不如配置文件灵活，因为没法设置 BASE_URL 和模型映射。

方式五：企业/云服务商认证

AWS Bedrock、Google Vertex AI 这些也支持，具体看 Anthropic 官方文档。

基本使用

启动交互式对话

最简单的方式，直接运行：

claude

进入交互模式，可以一直对话，直到你退出。

退出方式：

• • 输入 /exit
• • 或者按 Ctrl+C 两次

单次提问

不想进入交互模式，可以直接问一个问题：

claude "这个项目的入口文件在哪里"

问完就退出，不会保持会话。

带上下文提问

# 让 Claude 看某个文件
claude "帮我看看这个文件有什么问题" < src/app.js

# 或者指定文件路径
claude "解释一下这个文件的逻辑" --file src/utils/helper.ts

常用命令

在交互模式下，除了正常对话，还有一些斜杠命令可以用：

项目相关

会话管理

工具和能力

常用命令详解

/init — 生成项目上下文

在当前项目生成 CLAUDE.md 文件，自动分析代码结构并写入项目背景信息。

什么时候用：

• • 刚接手一个新项目，想让 Claude 快速了解全貌
• • 项目架构变了，需要更新上下文

注意事项：

• • 是一次性快照，生成后不会自动更新，项目变动后需要手动更新或重新生成
• • 会覆盖已有的 CLAUDE.md，生成前会询问是否覆盖

/compact — 压缩上下文

把当前会话的前面内容压缩成摘要，释放 token 空间，让后面的对话可以继续进行。

什么时候用：

• • 聊了很久，上下文越来越大，响应变慢的时候
• • 快要超出 token 限制的时候

工作原理：

• • 纯内存操作，不会写到磁盘文件
• • 压缩后的摘要留在当前会话里，退出终端就没了
• • 不影响你手动维护的 .session-context.md（你自己写的文件，不是 Claude 生成的）

/resume — 恢复之前的会话

从 Claude Code 的本地存储中恢复之前的会话记录，继续之前的对话。

什么时候用：

• • 同一台机器上中断后回来接着干

注意事项：

• • 恢复的是本地存储的会话记录，换台机器就恢复不了

/model — 切换模型

切换当前会话使用的 Claude 模型，比如 sonnet、opus、haiku 等。

用法：

/model sonnet   # 切换到 Sonnet
/model opus     # 切换到 Opus
/model haiku    # 切换到 Haiku

什么时候用：

• • 当前任务需要更强的模型（比如复杂推理用 Opus）
• • 想省 token 时切换到更轻量的模型（比如 Haiku）

配置文件

Claude Code 的配置文件在 ~/.claude/settings.json（Windows：C:\Users\你的用户名\.claude\settings.json），可以调整一些默认行为。

常见配置项

{
"permissions":{
"allow":[
"Bash(npm install)",
"Bash(npm test)",
"Bash(git status)"
],
"deny":[]
},
"env":{
"ANTHROPIC_API_KEY":"your-key-here"
}
}

权限配置

Claude Code 在执行一些操作时会请求权限，比如运行 shell 命令、编辑文件等。

你可以在配置里预先设置允许哪些操作，这样就不会每次都弹确认：

{
"permissions":{
"allow":[
"Bash(npm *)",
"Bash(git *)",
"Read",
"Edit"
]
}
}

这样设置后，运行 npm 和 git 命令、读文件、编辑文件都不会再问你了。

CLAUDE.md 文件

这是 Claude Code 特有的一个东西。

在项目根目录放一个 CLAUDE.md 文件，Claude 每次启动时会自动读取，用来了解你的项目背景。

这个文件写什么

• • 项目是什么、做什么用的
• • 技术栈是什么
• • 代码结构大概是怎样的
• • 有什么特殊约定或规范
• • 常见问题和注意事项

示例

# 项目说明

这是一个 React + TypeScript 的前端项目，后端是 Node.js + Express。

## 技术栈

- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express + PostgreSQL
- 样式：Tailwind CSS

## 目录结构

-`src/` - 前端源码
-`server/` - 后端代码
-`tests/` - 测试文件

## 开发约定

- 组件用函数式写法，不用 class
- API 请求统一放在 `src/api/` 目录
- 提交信息用中文

## 注意事项

- 数据库迁移文件在 `server/migrations/`，改完表结构记得生成迁移
- 环境变量在 `.env.example` 里有模板

生成 CLAUDE.md

如果不想自己写，可以让 Claude 帮你生成：

claude /init

它会扫描项目结构，自动生成一个初版的 CLAUDE.md，你再根据实际情况改改就行。

实际使用场景

场景一：理解现有代码

接手一个不熟悉的项目，或者看别人写的代码：

claude
> 帮我看看 src/utils/auth.ts 这个文件是做什么的
> 这个项目的 API 路由都在哪里定义的
> 数据库表结构是怎样的，有哪些表

场景二：写新功能

告诉 Claude 你要做什么，让它帮你写：

claude
> 帮我写一个用户注册的 API，要求：
  - 用 Express
  - 接收邮箱和密码
  - 密码要加密存储
  - 返回格式跟项目里其他 API 保持一致

它会看项目里现有的代码风格，尽量保持一致。

场景三：调试问题

代码报错了，让 Claude 帮忙排查：

claude
> 运行 npm start 报了这个错：
  Error: Cannot find module './config/database'
  帮我看看是什么问题

它会检查文件结构、导入路径，告诉你哪里出了问题。

场景四：代码重构

代码写得不好的地方，让 Claude 帮忙改：

claude
> src/components/UserList.tsx 这个文件太长了，有 500 多行
  帮我拆分成几个小组件

场景五：写测试

不想自己写测试用例：

claude
> 帮我给 src/utils/validate.ts 里的函数写单元测试
  用 Jest，覆盖主要场景和边界情况

场景六：跑命令AndGet结果

直接在 Claude 里跑命令，不用切出去：

claude
> 跑一下 npm test，看看有没有失败的测试
> 检查一下 git status，看看有哪些文件改了

使用技巧

1. 描述清楚你要什么

不要说”帮我优化这段代码”，要说”帮我优化这段代码，目标是减少数据库查询次数”。

越具体，Claude 给出的东西越靠谱。

2. 利用上下文

Claude Code 会记住当前会话的内容，所以可以连续对话：

> 帮我看看这个文件
> 第三十行的那个函数，能改一下吗
> 改完之后跑一下测试

不需要每次都重复背景信息。

3. 让它先看再做

如果要改代码，先让 Claude 看看现有代码：

> 先看看 src/api/user.js 现在的代码结构
> 然后帮我加一个删除用户的接口

这样它写出来的代码会更符合项目风格。

4. 及时清理上下文

聊了很久之后，上下文会变得很大，响应可能变慢。

用 /compact 压缩一下，或者 /clear 重新开始。

5. 用 CLAUDE.md 固定项目信息

每次新开会话都要重新解释项目背景，很烦。

把项目信息写在 CLAUDE.md 里，Claude 每次启动都会自动读取，省去重复说明。

常见问题

安装时报错 “permission denied”

权限问题，试试：

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

或者修改 npm 全局安装路径的权限：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

运行时提示 “node version too old”

Node.js 版本不够，需要 18+：

node --version  # 检查当前版本

如果版本低于 18，升级方法：

macOS/Linux（用 nvm）：

nvm install 18
nvm use 18

Windows（用 nvm-windows）：

nvm install 18
nvm use 18        # 需要管理员权限运行

Windows 的 nvm 和 macOS/Linux 的 nvm 不是同一个东西，需要用 nvm-windows。安装方式也不一样，去 GitHub 页面下载 nvm-setup.exe 安装就行。

登录时浏览器打不开

可能是服务器环境没有图形界面，可以手动复制链接：

claude login --no-browser

会给你一个链接，复制到本地浏览器打开就行。

响应很慢

可能是上下文太大了，用 /compact 压缩一下，或者 /clear 重新开始。

也可能是网络问题，检查一下能不能正常访问 Anthropic API。

总是提示要确认权限

在配置文件里设置允许的操作，参考前面”权限配置”部分。

费用相关

Claude Code 使用 Claude 的 API，会产生费用。

个人用户

• • 如果有 Claude Pro 订阅（$20/月），可以使用 Claude Code，额度包含在订阅里
• • 如果用 API Key，按 token 用量计费

查看费用

在交互模式下用 /usage 命令打开设置对话框，可以看到当前会话的 token 消耗，也能调整各种配置。

省钱建议

• • 问题描述清楚，避免反复修改
• • 及时用 /compact 或 /clear 清理上下文
• • 小任务用单次提问（claude "问题"），不要进入交互模式

跟其他工具的对比

选哪个看个人习惯。如果你已经在命令行里工作，Claude Code 会很顺手。如果你更喜欢图形界面，Cursor 可能更合适。

官方资源

• • 官方文档：https://docs.anthropic.com/en/docs/claude-code
• • GitHub：https://github.com/anthropics/claude-code
• • 问题反馈：https://github.com/anthropics/claude-code/issues