Claude Code国内安装配置完全指南：从环境搭建到成功运行

对于想要体验AI编程的开发者来说，Claude Code是目前最值得关注的命令行编码工具之一。它由Anthropic公司开发，定位为一个直接运行在终端中的AI编程助手，能够理解项目上下文、生成代码、执行命令并进行文件操作——与传统的IDE插件不同，它完全基于命令行交互，更贴近开发者的原生工作流。然而，国内用户在安装和配置过程中往往会遇到各种障碍——网络问题、环境配置、API密钥获取等。本文基于B站一位UP主的详细实战教程，整理出一份清晰的安装配置指南，帮助你快速跑通Claude Code的第一步。

环境准备：Node.js、Git和npm三件套

Claude Code的运行依赖三个基础环境：Node.js、Git和npm。这三者构成了整个工具链的基石，缺少任何一个都会导致后续步骤无法进行。

Node.js安装要点

Claude Code基于Node.js环境运行，因此这是第一个需要安装的组件。Node.js是一个基于Chrome V8引擎构建的JavaScript运行时环境，它让JavaScript代码能够脱离浏览器在服务器端或本地命令行中执行。Claude Code本质上是一个发布在npm注册表上的命令行工具包，它利用Node.js的异步I/O能力和丰富的生态系统来实现与AI模型的交互、文件系统操作和终端命令执行。npm（Node Package Manager）作为Node.js的默认包管理器，也是全球最大的开源软件注册表，托管了超过200万个JavaScript包，是安装Claude Code的直接渠道。

版本选择上有几个关键建议：

推荐LTS版本（长期维护版），稳定性更好，官方会持续维护。LTS版本通常会获得30个月的官方维护周期，包括安全补丁和关键bug修复，这对于依赖稳定运行环境的开发工具来说至关重要
版本不低于20，因为Claude Code是较新的工具，过低版本可能存在兼容问题。Node.js 20引入了多项性能改进和新的API特性，包括更完善的ES模块支持和改进的权限模型
Windows用户建议下载MSI安装包，它会自动配置环境变量；如果下载Zip包则需要手动配置
Mac用户选择PKG包，Linux用户选择对应的压缩包

安装完成后，在终端执行以下两个命令验证：

node --version
npm --version

两个命令都能正确输出版本号，说明Node.js环境就绑好了。

Git环境配置

Git的安装不仅仅是为了版本控制。Claude Code在执行任务时需要用到Git Bash提供的终端环境——它在Windows上模拟了一个可以运行Linux命令的mini终端。

具体来说，Git Bash是Git for Windows安装包中附带的一个终端模拟器，它基于MSYS2（Minimal SYS2）项目，在Windows上提供了一个类Unix的shell环境。这意味着开发者可以在Windows上使用ls、grep、cat、sed等Linux/Unix原生命令。Claude Code作为AI编码助手，在执行代码生成、文件创建、目录操作等任务时，底层会调用大量的shell命令。Windows原生的CMD和PowerShell虽然功能强大，但其命令语法与Unix系统存在显著差异。Git Bash弥合了这一差距，使得Claude Code可以使用统一的命令集在不同操作系统上运行。

安装Git后，同样执行命令验证：

git --version

这里有一个容易被忽略的细节：安装完Git后，需要将Git Bash的路径配置到环境变量中。具体来说，就是找到Git安装目录下的bash.exe文件路径（通常位于C:\\Program Files\\Git\\bin\\bash.exe）。环境变量（Environment Variables）是操作系统级别的键值对配置，其中PATH变量决定了系统能否在任意目录下找到可执行文件。如果不配这一步，后续让Claude Code执行生成项目、文件操作等任务时，系统将无法定位到bash解释器，很可能会报错。Windows用户可以通过"系统属性→高级→环境变量"界面进行配置，Mac/Linux用户则通常在.bashrc、.zshrc等shell配置文件中设置。

Git Bash终端环境

通过npm安装Claude Code本体

环境准备就绪后，安装Claude Code本身反而是最简单的一步。它通过npm一行命令即可完成：

Linux/Mac：需要在命令前加sudo提升权限（sudo是Unix/Linux系统中的超级用户权限提升命令，全局安装npm包需要写入系统级目录，因此需要管理员权限）
Windows：直接执行即可，不需要额外权限

如果下载速度慢，可以先配置npm的国内镜像仓库，将默认的国外源（registry.npmjs.org）切换为国内源（如淘宝镜像 registry.npmmirror.com），下载速度会有明显提升。镜像仓库本质上是官方npm注册表的国内同步副本，通常每隔几分钟就会与官方源同步一次，包的内容完全一致，只是物理服务器位于国内，网络延迟大幅降低。当然，如果已经有科学上网环境，这一步可以跳过。

安装完成后执行claude --version确认版本号，再执行claude --help可以查看所有可用的命令参数。

网络代理配置：国内用户的必经之路

这是整个配置过程中最关键也是最容易踩坑的环节。由于网络限制，国内用户直接运行Claude Code大概率会遇到区域限制的报错——Claude Code需要与Anthropic的API服务器建立HTTPS连接来发送和接收数据，而这些服务器部署在海外，直接访问可能会被阻断或出现极高延迟。

代理配置方案

解决方法是在项目目录下创建配置文件，将HTTP请求代理到科学上网的服务上：

在项目根目录创建.claude文件夹
在其中创建settings.json文件
配置HTTP和HTTPS的代理地址，指向本地的代理服务端口（通常格式为http://127.0.0.1:端口号，端口号取决于你使用的代理客户端设置，常见的有7890、1080等）

需要注意的是，除了在Claude Code的配置文件中设置代理外，还可以通过系统环境变量HTTP_PROXY和HTTPS_PROXY来为所有命令行程序设置全局网络代理。两种方式各有优劣：配置文件方式只影响Claude Code本身，更加精准；环境变量方式则对所有终端程序生效，配置一次即可。

如果你的命令行窗口已经配置了全局代理，或者在海外服务器上操作，则可以跳过这一步。但教程作者特别提到，网络状况时好时坏，建议一开始就把代理配好，避免执行到一半突然断连。

Claude Code教程封面

API密钥获取：两种可选路径

网络问题解决后，下一步是配置API密钥。API密钥（API Key）是一种身份认证机制，本质上是一串由服务提供商生成的唯一字符串，用于标识调用者身份并进行计费追踪。Anthropic的API密钥通常以sk-ant-为前缀。这里有两条路径可选：

官方直连方案

直接使用Anthropic官方服务，付费模式有两种：

订阅制：按月固定收费（如Claude Pro订阅为每月20美元，Max订阅为每月100美元或200美元），适合高频使用者，在订阅额度内没有明显的调用限制
按量计费：通过Anthropic Console充值后按实际API调用量扣费，适合偶尔使用的用户。计费基于输入和输出的token数量——token是大语言模型处理文本的基本单位，大约每个英文单词对应1-2个token，中文每个字大约对应1-2个token

使用官方服务时，首次启动Claude Code会引导你跳转到官网完成授权。这个过程遵循OAuth 2.0协议——一种行业标准的授权框架，通过浏览器跳转让用户在Anthropic官网上确认授权，然后将生成的访问令牌（token）回传给本地客户端。这种方式比直接粘贴API Key更安全，因为用户无需手动接触密钥明文。授权成功后，系统会自动获取token并写入本地配置文件（用户目录下的.claude.json），后续无需重复操作，直到token过期或被撤销。

第三方代理方案

如果不想直接对接官方服务，可以选择国内的第三方代理（即"套壳"服务）。它们的运作方式是：你调用第三方的API，第三方再代理调用Anthropic官方接口。从技术角度看，这本质上是一个反向代理（Reverse Proxy）架构——第三方在海外部署服务器，接收国内用户的API请求，将请求转发给Anthropic的官方API端点，再将响应结果原路返回给用户。

使用第三方服务时，除了配置API Key外，还需要额外配置一个API Base URL，将请求地址从Anthropic官方地址（如api.anthropic.com）切换到第三方的服务端点。具体配置方法一般在第三方平台的文档中会有说明。可以通过设置ANTHROPIC_BASE_URL环境变量或在配置文件中指定来完成。

教程作者给出了一个务实的建议：第三方服务主要解决的是网络问题，费用上不一定更便宜。如果只是想解决网络访问的痛点，可以考虑；但如果对成本敏感，需要仔细对比各家的定价。此外还需注意潜在的安全风险：你的所有对话内容和代码都会经过第三方服务器，存在数据泄露的可能性；第三方服务的稳定性和响应延迟也无法与官方直连相比。选择第三方服务时，建议优先考虑有良好口碑和透明隐私政策的平台。

登录授权与验证

所有配置完成后，在项目目录下执行claude命令，会进入一个初始化引导流程：

选择界面主题：亮色或暗色，纯粹的个人偏好
登录授权：跳转到Claude官网完成账号授权，或选择使用环境变量中自行配置的API Key。如果选择环境变量方式，需要预先设置ANTHROPIC_API_KEY环境变量，Claude Code会自动读取该变量完成认证
授权成功：控制台显示success，密钥信息写入本地配置

最终，当你看到"Welcome to Claude Code"的欢迎界面，并显示当前工作目录时，说明整个安装配置流程已经顺利完成。此时Claude Code已经可以感知你当前项目的文件结构，你可以开始用自然语言向它描述编程任务了。

常见问题速查

问题现象	可能原因	解决方案
区域限制报错	网络未配置代理	项目下创建`.claude/settings.json`配置代理，或设置`HTTP_PROXY`/`HTTPS_PROXY`环境变量
命令执行报错找不到bash	Git Bash路径未配置	将`bash.exe`路径加入系统PATH环境变量
npm安装速度极慢	默认使用国外镜像源	执行`npm config set registry https://registry.npmmirror.com`配置国内镜像
授权页面无法加载	网络不稳定	检查代理配置或切换网络环境
token过期需重新授权	OAuth令牌有效期已到	重新执行`claude`命令触发授权流程

这只是Claude Code系列教程的第一章——入门与配置。后续还会涉及核心模式切换（如自动模式与交互模式的区别）、Claude MD全局记忆（通过.claude/CLAUDE.md文件为AI提供项目级别的持久化上下文）、会话管理、资源监控等进阶内容。但万事开头难，把环境配置这一关顺利通过，后面的实战操作就水到渠成了。