Claude Code 安装与使用教程：从零配置到高效开发实战

平时在群里看别人演示 Claude Code 的时候，总觉得安装和使用门槛很高。一方面它是命令行工具，不像普通软件有可视化安装向导；另一方面它默认又需要配置 Anthropic 官方模型，很多人第一步就卡在了环境变量和密钥对接上，最后只能放弃。其实 Claude Code 的安装链路非常短，只要把 Node.js 环境和认证方式理顺，几分钟就能跑起来。这篇教程就围绕“从 0 到 1 完成 Claude Code 安装使用”这条主线展开，会覆盖 Windows、macOS、Linux 常见环境下的安装步骤，也会讲解如何用 API 方式接入第三方模型、如何开启自动模式避免频繁确认、如何压缩上下文节省成本，最后给出安装过程中最容易踩的坑和排查思路。

本文适合刚刚接触 Claude Code 的开发者，也适合已经在用但被各种“安装依赖”“兼容性报错”困扰的读者。学完之后，你能独立完成 Claude Code 的安装、认证、模型配置，并了解日常开发中最常用的命令和参数。

1. Claude Code 是什么，为什么要用它

1.1 Claude Code 的核心概念

Claude Code 是 Anthropic 推出的命令行编码智能体工具。它不是简单的代码补全插件，而是能直接在终端里理解项目结构、读取文件、执行命令、修改代码的 AI 编程助手。你可以在项目目录下启动它，让它分析代码、写测试、修复 Bug、解释逻辑，甚至执行 Git 操作。

很多初学者会把 Claude Code 和“聊天机器人”混为一谈，这是比较大的误解。传统 AI 聊天工具只能在你给它文本后返回文本，Claude Code 则更像一个“坐在终端里的结对程序员”。它可以感知当前目录下的文件内容，可以调用命令行的能力，可以在执行操作前征求你的确认。也就是说，它具备一定的 Agent 能力，而不仅仅是被动回答问题。

在专业定义上，Claude Code 可以理解为一个基于大语言模型构建的终端智能体框架。它由模型驱动，但工具调用机制由 CLI 客户端完成。它通过 API 与模型服务通信，从而完成代码读取、命令执行、文件修改等一系列操作。

1.2 常见应用场景

Claude Code 适合以下场景：

• 快速阅读并理解一个不熟悉的项目，让 AI 给你梳理模块结构。
• 在已有项目里按需求生成代码，并自动写入对应文件。
• 执行测试、运行构建命令、查看报错日志，再根据反馈自动修复。
• 处理重复性的编码任务，比如补充注释、生成单元测试、批量修改接口命名。
• 作为代码审查助手，对变更文件做静态检查并给出改进建议。

相比在网页端复制粘贴代码，使用 Claude Code 最直观的好处是它直接工作在你的项目上下文中。你不用把整个项目内容粘贴过去，它会自己读取需要的信息，然后针对当前分支、当前环境操作。对经常往返于 IDE 和终端之间的开发者来说，这种方式能省掉大量上下文切换时间。

1.3 Claude Code 与 Codex 的选择

网上经常看到有人讨论“Codex 和 Claude Code 哪个更强”。Codex 是 OpenAI 阵营的编程智能体，Claude Code 则来自 Anthropic 阵营，它们的使用方式非常相似：都是命令行工具，都强调 Agent 能力，都支持在项目上下文中操作文件。

从使用体验上看，两者主要通过底层模型来体现差异。Claude 系列模型在代码理解、长文本处理和指令遵循方面有自己的优势，Codex 则在部分场景下凭借 OpenAI 生态和工具链整合获得用户青睐。作为开发者，没必要陷入“谁取代谁”的争论，更合理的做法是都装到环境里，在不同项目或不同任务类型中选择合适的工具。Claude Code 的安装和使用并不复杂，真正重要的是理解它的 Agent 执行逻辑和权限确认机制。

2. 环境准备

2.1 不同系统的前置条件

Claude Code 官方推荐通过 Node.js 环境运行，所以安装前的第一件事是确认系统里有可用的 Node.js 环境。它本身是一个 npm 全局包，理论上只要 Node.js 版本满足要求，就能在 Windows、macOS、Linux 上运行。

需要的核心条件如下：

• Node.js 版本需要在官方要求的范围内，建议安装最新的 LTS 版本。
• 终端工具建议使用 Windows Terminal、macOS 自带 Terminal 或 iTerm2、Linux 下任意主流终端。
• 能正常访问 npm 官方仓库或已配置 npm 镜像源。
• 如果你要使用第三方模型 API，需要提前准备好服务商提供的接口地址和密钥。

在开始之前，建议先打开终端，执行下面的命令确认 Node.js 已安装：

node -v npm -v

如果能正常输出版本号，说明 Node.js 基础环境已经就绪。如果提示node不是内部或外部命令，说明 Node.js 尚未安装或没有加入系统 PATH，需要先解决这个问题。

2.2 Node.js 安装与版本确认

Node.js 的安装方式在不同系统上略有差异。

在 Windows 上，推荐直接到 Node.js 官网下载 Windows Installer 安装包，或者使用 winget 命令安装：

winget install OpenJS.NodeJS.LTS

在 macOS 上，推荐使用 Homebrew 安装：

brew install node

在 Linux 上，不同发行版差异较大。如果你的系统是 Ubuntu/Debian，可以使用 apt 安装，但 apt 仓库里的 Node.js 版本可能偏旧，更推荐使用 NodeSource 或 nvm 安装新版。nvm 是管理 Node.js 版本最灵活的方式：

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

安装完成后可以用node -v确认版本。部分国内网络环境下载 npm 包较慢，可以提前把 npm 镜像切换为国内镜像源，例如：

npm config set registry https://registry.npmmirror.com

这样做可以显著提升后面全局安装 Claude Code 的下载速度。

2.3 终端工具推荐

Claude Code 天然是为终端场景设计的，所以终端的选择会影响使用体验。Windows 自带的旧版cmd虽然能运行，但样式和快捷键支持都比较弱，不建议作为主力。

比较推荐的终端组合是：

• Windows 用户：Windows Terminal，配合 PowerShell 或 Git Bash。
• macOS 用户：系统自带 Terminal 或 iTerm2。
• Linux 用户：GNOME Terminal、Konsole 或 VS Code 内置终端都可以。

在启动 Claude Code 之前，建议确认终端能正常显示彩色输出和特殊字符。Claude Code 的交互界面依赖终端对 Unicode 和颜色的支持，如果终端配置过于老旧，可能会出现乱码或界面错乱。

3. Claude Code 安装全流程

3.1 通过 npm 全局安装

安装 Claude Code 最稳定的方式是通过 npm 全局安装。打开终端，执行：

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

这条命令会从 npm 仓库拉取 Claude Code 的 CLI 包，并注册全局命令。安装过程会输出一些进度信息，等待命令执行完成即可。如果安装过程中出现权限错误，Windows 用户可以尝试以管理员身份运行终端，macOS/Linux 用户可以在命令前加上sudo，但更推荐先检查 npm 全局目录的权限。

安装完成后，执行：

claude --version

如果能输出类似x.y.z的版本号，说明安装已经成功。这里不需要纠结具体版本号，因为 Claude Code 的版本迭代速度较快，不同版本的命令参数可能略有差异。后面在使用过程中，如果某个命令在当前版本中不可用，可以用claude --help查看完整的命令帮助。

3.2 验证安装是否正常

执行claude --version只是第一步，更完整的验证是启动一次 Claude Code 交互界面。在任意空目录下执行：

claude

首次启动时，终端会进入 Claude Code 的交互模式，底部会出现输入框。如果你还没有配置模型认证，系统会提示登录或设置 API Key。由于 Claude Code 需要连接模型服务才能回答问题，所以在没有配置认证信息前，交互界面可能无法正常响应。

需要说明的是，启动交互模式并不会修改项目文件，也不会自动执行危险命令。它只是进入了一个待命状态，等你输入指令。很多第一次使用的人在看到交互界面后不知道下一步该做什么，其实只需要直接输入自然语言即可，例如“介绍一下当前项目结构”。

3.3 桌面版与 IDE 插件的补充说明

除了 npm 安装的 CLI 版本，目前 Claude Code 还有桌面端和 IDE 插件的生态。搜索“ClaudeCode 桌面端”“ClaudeCode 桌面板下载”时能看到不少相关信息。桌面端的优势是提供了图形化窗口，降低了纯终端操作的心理门槛，但它的安装更方便，可能直接在官网或应用商店下载。

IDE 插件这里需要特别提醒：无论你安装的是 IntelliJ IDEA 插件还是 VS Code 扩展，它们的底层大多依然依赖 Claude Code CLI。也就是说，如果你没有先完成命令行版本的安装，仅仅安装 IDE 插件可能无法正常工作。典型现象是插件已经激活，但执行 AI 操作时报错“找不到 claude 命令”。

以 IntelliJ IDEA 为例，如果你在插件市场搜索到 Claude Code 插件，安装前要注意插件对 IDE 版本的要求。不同插件对 IDEA 版本的要求不同，通常新版插件会要求较新的 IDE 版本。建议先看插件详情页的系统要求，确定当前 IDEA 版本是否满足。如果版本不满足，最常见的表现是插件无法启用或功能按钮置灰。

3.4 麒麟系统安装注意事项

有些用户使用的是国产麒麟操作系统，这类系统本质上是 Linux 发行版，Claude Code 的安装思路与 Linux 类似。核心依赖依然是 Node.js，所以先确保系统里有可用的 npm 环境。

麒麟系统上常见的问题是 Node.js 源仓库版本比较旧，直接使用系统包管理器安装的 Node.js 可能无法满足 Claude Code 的要求。建议使用 nvm 或二进制压缩包方式安装较新版的 Node.js。安装完 Node.js 后，再执行：

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

如果安装过程中出现网络超时，可以按前面介绍的方式切换 npm 镜像源。此外，麒麟系统默认 shell 可能是 bash，终端对 Claude Code 的交互界面兼容性一般没有问题。但如果遇到界面显示异常，可以先尝试更新终端或改变终端字体设置。

4. 启动与首次配置

4.1 启动交互式终端

完成安装后，进入你的项目目录，执行：

cd your-project claude

Claude Code 会分析当前目录，并在底部生成输入框。此时你可以输入任意问题或指令。例如：

请解释这个项目的整体结构

它会读取目录结构、关键文件，然后给出分析结果。第一次使用时不建议直接让它“修改代码”，最好先以查询和解释为主，等熟悉了它的行为模式再逐步放权。

如果希望在非交互模式下快速提问，可以使用claude -p参数：

claude -p "用 python 写一个快速排序"

这种方式适合脚本调用或一次性提问，不会进入长驻交互界面。

4.2 登录与 API Key 配置

Claude Code 的认证方式有两种主流选择：登录 Anthropic 账号使用订阅额度，或者配置 API Key 按量计费。如果你拥有 Anthropic 官方账号，启动时按提示链接账号即可。如果你更习惯 API 方式，可以通过环境变量指定密钥。

在终端中临时配置 API Key：

export ANTHROPIC_API_KEY="你的密钥"

在 Windows PowerShell 中：

$env:ANTHROPIC_API_KEY="你的密钥"

这种方式只在当前终端窗口生效，关闭终端后失效。也可以把环境变量写入 shell 配置文件，持久化生效，例如在~/.bashrc或~/.zshrc中追加：

export ANTHROPIC_API_KEY="你的密钥"

修改后执行source ~/.bashrc使其生效。需要特别注意的是，不要把 API Key 提交到 Git 仓库，否则会导致密钥泄露。

4.3 接入 DeepSeek 等第三方模型的思路

很多用户希望把 Claude Code 接入 DeepSeek 等第三方模型，主要目的是降低使用成本，或者使用国内服务商提供的模型接口。实现思路并不复杂：Claude Code 本身支持通过环境变量指定 Anthropic 兼容接口，只需要把基础地址和密钥指向第三方服务商即可。

常见的配置方式如下：

export ANTHROPIC_BASE_URL="你的服务商提供的兼容接口地址" export ANTHROPIC_AUTH_TOKEN="你的服务商密钥"

这里有两个点需要注意。第一，不同服务商提供的兼容接口地址不同，而且可能会随服务商策略调整，所以不要盲目复制网上的某个地址，要以服务商官方文档为准。第二，如果你之前配置了ANTHROPIC_API_KEY，在接入第三方模型时，可能需要优先使用ANTHROPIC_AUTH_TOKEN或修改 base URL 指向第三方地址，否则可能仍会请求 Anthropic 官方接口。

配置完成后，启动 Claude Code 时可以指定模型参数：

claude --model 模型名称

具体模型名称同样以服务商提供的信息为准。如果在启动时遇到鉴权失败，优先检查接口地址、密钥和模型名是否匹配。需要强调一点：不要在生产环境中随意使用不明确的第三方接口，尤其是涉及敏感项目代码时，务必确认服务商的数据处理策略和合规性。

5. 核心使用技巧

5.1 常用命令速查

Claude Code 的常用操作并不复杂，核心可以通过以下命令完成：

这些命令在不同版本中可能略有差异，建议在安装后执行claude --help查看你当前版本支持的参数。

5.2 不用一直点确认：自动模式

很多用户搜索“Claude Code 如何不用一直点确认”，说明被频繁的权限确认困扰。Claude Code 默认是安全取向的，执行命令前会询问你是否允许。这在防止 AI 误操作方面很有价值，但在连续执行多个步骤时，也确实会打断节奏。

减少确认可以从两个方向入手。第一个方向是使用-a参数，让 Claude Code 自动接受一些相对常规的操作确认：

claude -a

第二个方向是使用--dangerously-skip-permissions，它会跳过所有权限确认，让 AI 直接执行命令、修改文件。这个选项名称里的 “dangerously” 已经说明风险很高，它适合在隔离的测试环境、一次性容器、或者你完全信任当前任务场景时使用。在真实工程项目中不建议开启，因为一旦模型理解出现偏差，可能执行错误的删除或修改命令。

更好的做法是分场景切换：日常开发用默认的确认模式，批量执行重复任务时再用-a，只有在你完全清楚后果时才使用跳过所有权限的模式。

5.3 压缩上下文：/compact

Claude Code 在长时间对话后，会把大量历史信息计入上下文，导致 token 消耗增加，模型响应也可能变慢。这时可以使用/compact命令压缩上下文。在交互界面中直接输入：

/compact

它会总结当前对话核心信息，并重新生成一份精简上下文。这个技巧在长会话里非常实用，尤其是在处理大型文件或复杂项目时，能显著节省成本并保持模型响应质量。

需要注意的是，/compact属于会话内的命令，类似聊天窗口里的“重开新话题”。如果你正在进行一个连续性很强的任务，压缩后 AI 可能会丢失部分细节，建议在任务告一段落时再执行。

5.4 清空输入与快速取消

有用户问“用 cmd 窗口启动 Claude Code 之后，怎么快速清空已经输入但没有发送请求的字”。这类问题本质上是终端输入编辑的问题，不是 Claude Code 独有的。

在大多数终端中，如果输入框里已经有内容但还没有发送，可以通过以下方式清空：

• 按Ctrl+C取消当前输入状态，回到干净的提示界面。
• 按Ctrl+U清空当前输入行，这个快捷键在 Unix-Like 终端里很常见。
• Windows Terminal 的默认设置也支持 Ctrl 快捷键组合，可以在设置中查看。

最稳妥的办法是直接用退格键删除，或者全选后删除。如果输入内容较多，用Ctrl+C往往更干脆。不同终端实现不同，建议在自己的终端里实际测试一次。需要说明的是，Ctrl+C在某些终端里可能被理解为“发送中断信号”，不同版本的 Claude Code 对取消输入的处理方式不完全一样，但多数情况下它不会退出程序，只会取消当前输入。

5.5 IDEA 插件与 Trae 集成

如果你不想完全离开 IDE，可以尝试 Claude Code 的相关插件。以 IntelliJ IDEA 为例，打开插件市场，搜索 “Claude Code”，安装后通常需要指定本机 claude 可执行文件路径，或者在 IDE 设置中配置模型端点。插件安装前要确认 IDEA 版本是否满足插件要求，一般较新版本插件会要求 2023.x 以上版本，但具体以插件页说明为准。

另一类尝试是把 Claude Code 整合进 Trae。Trae 本身是 AI 原生的编辑器，自带不少 AI 能力。关于“Trae 如何集成 Claude Code”，目前主要有两种思路：第一种是在 Trae 的终端里直接调用claude命令，把 Claude Code 作为终端工具使用；第二种是查看 Trae 的插件或 MCP 市场里是否提供 Claude Code 接入能力。MCP 是一种模型能力扩展协议，具体的配置方式会随编辑器版本更新而变化，建议以官方文档为准，不要照搬网上可能已经过时的配置。

6. 常见问题与排查思路

6.1 Windows 报错 missing hcs services: hns, vmcompute, vfpext

很多 Windows 用户在安装或运行 Claude Code 时遇到如下报错：

missing hcs services: hns, vmcompute, vfpext

这不是 Claude Code 本身的代码问题，而是系统缺少 Windows 容器或 Hyper-V 相关的服务。hns是 Host Network Service，vmcompute是 Hyper-V Host Compute Service，vfpext是虚拟过滤平台扩展，它们通常用于 WSL2、Docker Desktop 或 Windows 容器场景。

排查时可以按以下步骤处理：

1. 按Win + R，输入services.msc，查看vmcompute服务是否存在并已启动。
2. 如果服务被禁用，右键修改为手动或自动并启动。
3. 检查 Windows 功能里是否开启“虚拟机平台”和“Hyper-V”。
4. 如果用的是 WSL2 环境，还需要确认wsl --status正常。
5. 如果仍然报错，建议以管理员身份运行 PowerShell，执行：

Get-Service vmcompute, hns

根据输出结果确认服务状态。如果服务列表中看不到 hns，通常需要检查 Windows 版本和容器功能是否安装完整。这个问题更多是环境问题，与 Claude Code 的 npm 包本身没有直接关系。

6.2 安装程序提示与 64 位 Windows 不兼容

有用户反馈，下载 Claude Code 桌面版后，安装时提示“由于与 64 位版本的 Windows 不兼容，此程序或功能无法启动”。这个报错常见于桌面安装包，而不是 npm 安装的 CLI 版本。

可能的原因有几个：

• 下载的安装包损坏或不完整。
• 系统缺少必要的运行库，例如 VC++ Redistributable。
• 当前系统版本过旧，不满足桌面版的最低系统要求。
• 安装包被安全软件拦截或修改。

建议处理方式：

1. 检查系统信息，确认系统确实是 64 位。
2. 重新下载最新版安装包。
3. 安装最新的 Visual C++ 运行库。
4. 以管理员身份运行安装程序。

如果不急于使用桌面版，可以直接使用 npm 安装 CLI 版本，绕过桌面安装包的问题。CLI 版本在大多数情况下功能完整，桌面端更多是提供图形化包装。

6.3 npm 安装缓慢或超时

npm 安装@anthropic-ai/claude-code时卡住，通常和网络到 npm 官方仓库的连通性有关。解决办法是切换 npm 镜像源：

npm config set registry https://registry.npmmirror.com

切换后可以重新执行安装命令。如果公司内部有 npm 私有仓库，也可以使用公司内网镜像。安装完成后，claude --version能成功输出版本号，就说明安装链路已经打通。

6.4 无法连接第三方 API

配置了 DeepSeek 或其它第三方 API 后，启动 Claude Code 仍报连接失败，需要按顺序排查：

1. 接口地址对不对？路径末尾是否需要带/anthropic之类的后缀，以服务商文档为准。
2. 密钥是否有效？有些服务商需要新建专属 API Key，而不是使用网页登录密码。
3. 环境变量是否正确读取？可以在终端执行echo $ANTHROPIC_BASE_URL查看。
4. 模型名称是否匹配？不同服务商对模型名称的命名不同。
5. 服务商账户是否欠费或限流？

这类问题绝大部分是配置细节不匹配，而不是 Claude Code 本身的问题。建议先通过 curl 请求接口地址，验证密钥和模型名是否可用，再回到 Claude Code 中排查。

6.5 会话卡住或响应异常

如果 Claude Code 进入会话后长时间没有响应，可能是网络问题、服务端限流，也可能是模型服务不稳定。优先执行以下操作：

• 输入/status或直接按Esc查看当前状态。
• 按Ctrl+C取消当前请求。
• 关闭会话后，用claude --continue恢复上一次上下文。
• 尝试切换网络，或在公司代理环境下检查系统代理配置。

如果反复出现响应为空，可以考虑更新 Claude Code 版本：

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

新版通常修复了已知的交互和连接问题。

7. 最佳实践与工程建议

7.1 权限控制与最小授权

Claude Code 默认的权限确认机制不是阻碍效率的累赘，而是一道安全防线。在真实项目中，建议只在可信项目里开启自动确认，在涉及生产环境、数据库操作或删除命令时，始终保留人工确认步骤。

即使你使用了--dangerously-skip-permissions，也只建议在测试环境验证。执行带删除、覆盖、重启服务这类高影响操作之前，最好先让 AI 输出将要执行的命令，人工确认后再手动执行。最小权限原则不仅适用于系统账号，也适用于给 AI 的权限边界。

7.2 密钥管理

不要把 API Key 写在项目代码里，也不要直接硬编码在package.json或.env并提交到仓库。推荐的做法是：

• 使用本地.env文件并加入.gitignore。
• 使用系统环境变量或密钥管理工具。
• 定期更换密钥，发现泄露立即吊销。

如果使用第三方模型 API，最好为不同项目创建不同 Key，方便隔离和审计。密钥成本控制也很重要，API 方式通常按 token 计费，长会话中的上下文会快速累积，建议定期使用/compact压缩。

7.3 上下文管理与成本控制

Claude Code 的能力强，但上下文并不是无限的。超过模型窗口后，它会截断或总结历史，这可能导致任务连续性下降。在实际工程中，建议把大任务拆成多个小任务，每个会话聚焦一个目标。例如先让 AI 分析设计，再让它生成骨架，再让它实现具体模块。不要在一个会话里同时处理十几个无关需求。

另外，对大型项目，可以引导 AI 只读取必要的目录和文件，减少不必要的 token 消耗。你也可以通过.claude配置或项目说明文件，让 Claude Code 更了解项目约定。

7.4 日志与调试

当 Claude Code 执行结果不符合预期时，不要急着指责 AI。先看看它的执行逻辑，检查它读取了哪些文件、执行了哪些命令。Claude Code 在交互界面中会展示操作记录，养成阅读这些日志的习惯能帮助你理解它的决策过程。

如果使用了 IDE 插件，也要学会查看插件输出日志。大部分 IDE 插件会提供日志窗口，错误信息里往往会明确提示是 CLI 缺失、版本不兼容还是权限问题。

7.5 安全边界

Claude Code 的本质是让模型能够执行命令和修改文件，这意味着它的能力边界由你授予的权限决定。不要把 Claude Code 运行在未授权的系统上，尤其不能在敏感的生产服务器上随意安装并赋予高权限。使用前务必确认你的操作符合公司或项目组的安全规范，获得合法授权后再在测试环境验证。

如果你在公司内网环境使用，还需要注意模型服务商的数据合规要求。不要把内部敏感源码、数据库密码、隐私数据直接发给未经企业批准的第三方模型服务。建议优先使用企业认证的服务接口，或者只在脱敏后的代码片段上使用。

8. 总结：10分钟上手后的下一步

如果按这篇文章的步骤操作，10 分钟左右你就能完成 Claude Code 的安装和基础配置。刚装完时不要急着把所有权限都放开，先在小型项目里试水，用自然语言让它分析项目、写测试、修 Bug，逐步建立对工具“行为习惯”的信任感。

能跑通安装只是第一步，真正提高效率的地方在于使用习惯：用/compact控制上下文、用-a和全跳过权限模式区分场景、用非交互模式接入脚本、用 IDE 插件和 Trae 等工具把它嵌入日常工作流。后续可以继续研究 Claude Code 的配置文件、自定义 Skill、模型切换和 MCP 扩展能力，这些都是能加深工具利用率的方向。

如果在安装使用过程中遇到本文没有覆盖的报错，最直接的办法是跑一遍claude --help，并根据报错关键词搜索解决方案。大多数问题都集中在 Node.js 版本、API 地址、密钥权限和系统服务这四个方面，按顺序排查基本能解决。

希望这篇教程能帮你少走弯路，顺利把 Claude Code 用起来。