Claude Code 是 Anthropic 推出的命令行 AI 编程助手，具备强大的自主 Agent 能力，能够直接在终端中协助你完成代码编写、调试、重构等任务。无论你是初次尝试 AI 编程助手，还是希望进一步挖掘 Claude Code 的潜力，这篇指南都将为你梳理从安装到进阶使用的关键环节，帮助你快速上手并高效运用。

开始使用

参考：Claude Code 官方文档

安装方式

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

npm 全局安装：

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

依赖 Node.js 18+ 环境，且使用此方式安装后需手动更新，正逐步被官方弃用，推荐使用 PowerShell 或 CMD 安装。

验证安装

claude -v

安装故障排除

下面主要是通过 PowerShell 与 CMD 安装时可能会遇到的问题。

注

CMD 与 PowerShell 并不是一个东西。在你输入安装命令后，如果看到 The token '&&' is not a valid statement separator，说明你在 PowerShell 中；如果看到 irm' is not recognized as an internal or external command，说明你在 CMD 中。当你在 PowerShell 时，提示符显示为 PS C:\；当你在 CMD 时，提示符显示为不带 PS 的 C:\。

网络连接问题

PS C:\Users\1> irm https://claude.ai/install.ps1 | iex
Setting up Claude Code...

✘ Installation failed

Failed to fetch version from https://downloads.claude.ai/claude-code-releases/latest after 3 attempt(s): ECONNREFUSED

Try running with --force to override checks
irm https://claude.ai/install.ps1 | iex : Installation failed (exit code 1)
所在位置 行:104 字符: 5
+     Write-Error "Installation failed (exit code $installExitCode)"
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException

如果在 PowerShell 输入安装命令，出现 ECONNREFUSED，这是由于网络问题，请求被拒绝了。具体来说，安装脚本在尝试连接 https://downloads.claude.ai 来获取最新版本信息时，连接被拒绝了。这通常不是脚本本身的问题，而是你的本地网络环境阻止了这次访问。

问题出现原因主要有以下几种可能：

• 网络代理/VPN：如果你在使用 VPN 或代理，PowerShell 默认可能没有使用这些代理设置，导致流量没有走代理通道。
• 防火墙或安全软件：系统防火墙、杀毒软件或其他安全工具可能误将安装脚本的连接请求拦截了。
• 地区网络限制：从某些地区直接访问 claude.ai 的服务器可能会受到限制。
• DNS 解析问题：你的 DNS 服务器可能无法正确将 downloads.claude.ai 的域名解析为 IP 地址。
• Claude 服务器问题：虽然可能性较小，但也不排除 Claude 的下载服务器暂时不可用。

你可以按照下面的步骤，从易到难逐一尝试：

1. 检查并配置代理（最常见） 这是最可能的原因。如果你在使用代理工具（如 Clash、V2Ray 等），需要告诉 PowerShell 使用你的代理。请把端口号（如 7890）换成你自己代理软件监听的端口。

   # 在 PowerShell 中执行以下命令（注意替换端口号）
   $env:HTTP_PROXY="http://127.0.0.1:你的代理端口"
   $env:HTTPS_PROXY="http://127.0.0.1:你的代理端口"
   
   # 然后重新运行安装命令
   irm https://claude.ai/install.ps1 | iex

2. 临时关闭防火墙或安全软件 为了测试，可以尝试暂时禁用 Windows Defender 防火墙或任何第三方杀毒软件（如 360、火绒等），然后重新运行安装命令。请注意：测试完后务必重新开启这些安全防护。

3. 更换 DNS 服务器 可以尝试将你的 DNS 服务器修改为公共 DNS，如谷歌的 8.8.8.8 和 8.8.4.4，或者国内常用的 114.114.114.114，以排除 DNS 解析问题。

4. 检查网络连接 在浏览器中访问 https://claude.ai，检查是否能正常打开。如果不能，说明你的网络环境确实无法直接访问 Claude 的服务器。

5. 使用 npm 安装（备用方案） 如果以上方法都无效，可以考虑使用你之前提到的 npm 方式进行安装。虽然它不是官方未来主推的方式，但在网络受限的环境下，通过包管理器安装有时能绕过一些限制。

缺少 PATH

如果安装成功但运行 claude 时出现 command not found 或 not recognized 错误，或者在安装阶段出现过以下警告⚠️：

⚠ Setup notes:
  ● Native installation exists but C:\Users\Micheal.Zheng\.local\bin is not in your PATH. Add it by opening: System
    Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart your terminal.

这是因为安装目录不在您的 PATH 中，系统还不知道去哪里找这个新安装的程序。

手动添加 PATH

Win + R 输入 sysdm.cpl -> 高级 -> 环境变量，在用户环境变量 Path 中，新建 C:\Users\你的用户名\.local\bin 或 %USERPROFILE%\.local\bin。也可以使用下方命令快速添加。

命令添加 PATH

Windows PowerShell

$env:PATH -split ';' | Select-String '\.local\\bin'

如果没有输出，输入以下命令将安装目录添加到您的用户 PATH：

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Windows CMD

echo %PATH% | findstr /i "local\bin"

如果没有输出，则手动添加用户 PATH 变量。

重启终端后使用 claude -v 验证。

其它故障处理参考官网文档 故障排除。

使用第三方 API

Claude Code 默认使用 Anthropic 官方的 Claude 模型。如果你尚未订阅 Claude Pro 或开通 API 额度，可以通过配置第三方 API 来使用其他兼容的模型提供商（如 DeepSeek 等）。

方案一：使用 CCSwitch（推荐）

CCSwitch 是一款社区工具，可帮助你在不同 API 提供商之间无缝切换。安装后在 CCSwitch 配置文件中添加目标 API 的 Endpoint 和 Key 即可，推荐使用此方式。

方案二：通过 settings.json 配置

编辑 Claude Code 的配置文件（~/.claude/settings.json），编辑环境变量，添加并修改为指定模型与 API key：

{
  "env": {
    // 你的 API 认证密钥（必填）
    "ANTHROPIC_AUTH_TOKEN": "<你的 API Key>",
    // API 服务地址（必填，填入第三方兼容接口地址）
    "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
    // 指定 Haiku 模型（轻量任务、子代理常用），一般修改为同系列能力较低模型，如 deepsee-v4-flash
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<haiku 模型名>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "<haiku 显示名称>",
    // 指定 Opus 模型（高复杂度任务），一般修改为同系列中最强模型，deepsee-v4-pro
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<opus 模型名>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "<opus 显示名称>",
    // 指定 Sonnet 模型（日常编码主力模型）,一般修改为同系列中最强模型，deepsee-v4-pro
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<sonnet 模型名>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "<sonnet 显示名称>",
    // 全局默认模型（优先级最高，覆盖上述各模型指定）
    "ANTHROPIC_MODEL": "<默认模型名>",
    // 子代理（Agent 调用子任务）使用的模型
    "CLAUDE_CODE_SUBAGENT_MODEL": "<子代理模型名>"
  }
}

注

标准 JSON 不支持注释。上方注释仅用于理解各字段含义。

方案三：通过环境变量配置

设置以下环境变量即可覆盖默认 API 配置：

# Windows PowerShell
# API 服务地址（必填，填入第三方兼容接口地址）
$env:ANTHROPIC_BASE_URL="https://api.example.com/anthropic"
# 你的 API 认证密钥（必填）
$env:ANTHROPIC_AUTH_TOKEN="<你的 API Key>"
# 全局默认模型（优先级最高，覆盖下方各模型指定）
$env:ANTHROPIC_MODEL="<默认模型名>"
# 指定 Opus 模型（高复杂度任务）
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="<opus 模型名>"
# 指定 Sonnet 模型（日常编码主力模型）
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="<sonnet 模型名>"
# 指定 Haiku 模型（轻量任务、子代理常用）
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="<haiku 模型名>"
# 子代理（Agent 调用子任务）使用的模型
$env:CLAUDE_CODE_SUBAGENT_MODEL="<子代理模型名>"
# 推理努力级别：low / medium / high / max
$env:CLAUDE_CODE_EFFORT_LEVEL="max"

快捷方式

如果你有一个常用的 Claude 工作目录，每次在终端输入 claude 开始会话较为繁琐，可以创建一个快捷方式，将目标设置为：

cmd /k "cd /d "你的工作目录绝对路径（D:\my-claude-workspace）" && claude"

这样每次双击即可直接在指定工作目录下启动 Claude Code 会话。

CLAUDE.md

Claude Code 通过项目根目录下的 CLAUDE.md 文件实现记忆功能。这个文件可以存储：

• 项目描述：项目目标、架构、技术栈
• 编码规范：命名约定、代码风格偏好
• 常用命令：构建、测试、部署命令
• 工作流说明：团队协作流程、分支策略

Claude Code 在每次会话中会自动读取 CLAUDE.md，将其中内容作为系统上下文，让你不必重复说明项目背景。

相关详细内容参考 Claude 如何记住你的项目。

Skills

Skills 是 Claude Code 的插件系统，让 AI 具备特定领域的专业能力。

添加自定义 Skill

在项目或用户目录下创建 skills 文件夹，放入遵循 Skill 规范的 Markdown 文件即可。一个典型的 Skill 文件包含：

• 元数据：名称、描述、触发条件
• 指令：该 Skill 的行为逻辑
• 示例：使用场景和预期输出

---
name: my-skill
description: 自定义 Skill 示例
---

当你触发特定指令时，Claude Code 会加载此 Skill 并按其定义执行。

Skills 市场

社区贡献的 Skills 可以在以下平台找到：

The Agent Skills Directory

这里汇集了各类实用 Skills —— 从代码审查到数据库操作，从 DevOps 到文档生成，按需安装即可。

成本控制

Claude Code 的 token 消耗即成本，合理控制能显著降低使用费用。

1. 压缩对话

随着对话进行，上下文窗口中的历史信息会不断增加，消耗大量 token。

• 作用：压缩历史对话，保留关键上下文，丢弃冗余信息
• 好处：减少 token 消耗、降低响应延迟、保持对话质量
• 命令：输入 /compact 即可自动压缩当前对话

2. 提示词优化

精简的提示词 = 更少的 token = 更低的成本。推荐做法：

• 明确指定文件路径：修改 src/utils.ts 中的 formatDate 函数 而非 修改那个日期格式化函数
• 一次只做一件事：将多个需求拆分为独立对话
• 避免重复上下文：已在 CLAUDE.md 中记录的项目信息无需反复说明

3. 忽略文件

创建 .claudeignore 文件，告诉 Claude Code 哪些文件/目录不需要读取：

node_modules/
dist/
.git/
*.log
*.lock

合理配置后，Claude Code 检索代码时跳过无关目录，既节省 token 又提升响应速度。

4. 用量监控

CCSwitch 用量监控：

如果使用 CCSwitch 管理 API 路由，可在其面板中查看各服务的 token 消耗和费用统计。

命令统计：

输入 /usage，可查看当前会话的 token 消耗、估算费用和会话时长。

卸载

原生安装

如果你使用的是 Claude Code 上手指南 > 安装方式 中的前两种方式则为原生安装，删除 Claude Code 二进制文件和版本文件：

Windows PowerShell

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

npm 安装

删除全局 claude-code 包：

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

编辑此页

贡献者: zhenghaoyang24

上一页上下文工程：决定 Agent 能力上限的不是模型，而是它看到什么

下一页Vue3 响应式原理