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 claudeClaude Code 会分析当前目录并在底部生成输入框。此时你可以输入任意问题或指令。例如请解释这个项目的整体结构它会读取目录结构、关键文件然后给出分析结果。第一次使用时不建议直接让它“修改代码”最好先以查询和解释为主等熟悉了它的行为模式再逐步放权。如果希望在非交互模式下快速提问可以使用claude -p参数claude -p 用 python 写一个快速排序这种方式适合脚本调用或一次性提问不会进入长驻交互界面。4.2 登录与 API Key 配置Claude Code 的认证方式有两种主流选择登录 Anthropic 账号使用订阅额度或者配置 API Key 按量计费。如果你拥有 Anthropic 官方账号启动时按提示链接账号即可。如果你更习惯 API 方式可以通过环境变量指定密钥。在终端中临时配置 API Keyexport 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在当前目录启动交互式会话claude --version查看版本号claude --help查看完整命令帮助claude -p 问题非交互模式直接返回结果claude --continue继续上一次会话claude --model 模型名指定模型claude -a自动接受部分操作减少确认claude --dangerously-skip-permissions跳过全部权限确认高风险这些命令在不同版本中可能略有差异建议在安装后执行claude --help查看你当前版本支持的参数。5.2 不用一直点确认自动模式很多用户搜索“Claude Code 如何不用一直点确认”说明被频繁的权限确认困扰。Claude Code 默认是安全取向的执行命令前会询问你是否允许。这在防止 AI 误操作方面很有价值但在连续执行多个步骤时也确实会打断节奏。减少确认可以从两个方向入手。第一个方向是使用-a参数让 Claude Code 自动接受一些相对常规的操作确认claude -a第二个方向是使用--dangerously-skip-permissions它会跳过所有权限确认让 AI 直接执行命令、修改文件。这个选项名称里的 “dangerously” 已经说明风险很高它适合在隔离的测试环境、一次性容器、或者你完全信任当前任务场景时使用。在真实工程项目中不建议开启因为一旦模型理解出现偏差可能执行错误的删除或修改命令。更好的做法是分场景切换日常开发用默认的确认模式批量执行重复任务时再用-a只有在你完全清楚后果时才使用跳过所有权限的模式。5.3 压缩上下文/compactClaude Code 在长时间对话后会把大量历史信息计入上下文导致 token 消耗增加模型响应也可能变慢。这时可以使用/compact命令压缩上下文。在交互界面中直接输入/compact它会总结当前对话核心信息并重新生成一份精简上下文。这个技巧在长会话里非常实用尤其是在处理大型文件或复杂项目时能显著节省成本并保持模型响应质量。需要注意的是/compact属于会话内的命令类似聊天窗口里的“重开新话题”。如果你正在进行一个连续性很强的任务压缩后 AI 可能会丢失部分细节建议在任务告一段落时再执行。5.4 清空输入与快速取消有用户问“用 cmd 窗口启动 Claude Code 之后怎么快速清空已经输入但没有发送请求的字”。这类问题本质上是终端输入编辑的问题不是 Claude Code 独有的。在大多数终端中如果输入框里已经有内容但还没有发送可以通过以下方式清空按CtrlC取消当前输入状态回到干净的提示界面。按CtrlU清空当前输入行这个快捷键在 Unix-Like 终端里很常见。Windows Terminal 的默认设置也支持 Ctrl 快捷键组合可以在设置中查看。最稳妥的办法是直接用退格键删除或者全选后删除。如果输入内容较多用CtrlC往往更干脆。不同终端实现不同建议在自己的终端里实际测试一次。需要说明的是CtrlC在某些终端里可能被理解为“发送中断信号”不同版本的 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 Servicevmcompute是 Hyper-V Host Compute Servicevfpext是虚拟过滤平台扩展它们通常用于 WSL2、Docker Desktop 或 Windows 容器场景。排查时可以按以下步骤处理按Win R输入services.msc查看vmcompute服务是否存在并已启动。如果服务被禁用右键修改为手动或自动并启动。检查 Windows 功能里是否开启“虚拟机平台”和“Hyper-V”。如果用的是 WSL2 环境还需要确认wsl --status正常。如果仍然报错建议以管理员身份运行 PowerShell执行Get-Service vmcompute, hns根据输出结果确认服务状态。如果服务列表中看不到 hns通常需要检查 Windows 版本和容器功能是否安装完整。这个问题更多是环境问题与 Claude Code 的 npm 包本身没有直接关系。6.2 安装程序提示与 64 位 Windows 不兼容有用户反馈下载 Claude Code 桌面版后安装时提示“由于与 64 位版本的 Windows 不兼容此程序或功能无法启动”。这个报错常见于桌面安装包而不是 npm 安装的 CLI 版本。可能的原因有几个下载的安装包损坏或不完整。系统缺少必要的运行库例如 VC Redistributable。当前系统版本过旧不满足桌面版的最低系统要求。安装包被安全软件拦截或修改。建议处理方式检查系统信息确认系统确实是 64 位。重新下载最新版安装包。安装最新的 Visual C 运行库。以管理员身份运行安装程序。如果不急于使用桌面版可以直接使用 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 仍报连接失败需要按顺序排查接口地址对不对路径末尾是否需要带/anthropic之类的后缀以服务商文档为准。密钥是否有效有些服务商需要新建专属 API Key而不是使用网页登录密码。环境变量是否正确读取可以在终端执行echo $ANTHROPIC_BASE_URL查看。模型名称是否匹配不同服务商对模型名称的命名不同。服务商账户是否欠费或限流这类问题绝大部分是配置细节不匹配而不是 Claude Code 本身的问题。建议先通过 curl 请求接口地址验证密钥和模型名是否可用再回到 Claude Code 中排查。6.5 会话卡住或响应异常如果 Claude Code 进入会话后长时间没有响应可能是网络问题、服务端限流也可能是模型服务不稳定。优先执行以下操作输入/status或直接按Esc查看当前状态。按CtrlC取消当前请求。关闭会话后用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 用起来。