Claude Code 安装配置 入门教程

Claude Code 是由 Anthropic 提供的命令行 AI 编程助手，让你在终端内直接用自然语言与 Claude 交互，轻松完成代码生成、审查、重构与调试等任务。安装配置过程简明扼要，仅需三步：安装 Node.js（版本 18 或 20）、通过 npm 全局安装 @anthropic-ai/claude-code 包、使用 claude 命令启动并完成 API 密钥认证。全程纯命令行操作，不依赖图形界面，专为习惯终端工作流的开发者设计。

开始之前

在安装之前，请确保满足以下条件，这能避免约 80% 的常见初始错误。

下一步：claude code mac 安装、claude code windows 安装教程

系统与权限要求

Claude Code 支持 macOS 10.15+ 及主流 Linux 发行版（如 Ubuntu 20.04+、Debian 11+、CentOS 7+）。Windows 用户需先安装 WSL 2，并在其 Linux 环境中运行。

终端需具备对 ~/.config/ 目录的写入权限，因为 Claude Code 会将配置文件和认证令牌存储在此处。若使用公司锁定的设备，请提前确认是否有权安装全局 npm 包或修改 shell 配置文件。

必备软件

软件	最低版本	检查命令	备注
Node.js	18.x 或 20.x	node -v	官方明确推荐使用 Node.js 18 或 20 的 LTS 版——21 和 22 未经完整测试，可能遇到兼容性问题
npm	9.x 或更高	npm -v	通常随 Node.js 自动安装
git	2.x 或更高	git --version	虽非强制要求，但 Claude Code 的核心功能（如代码搜索和 diff 生成）依赖于 git 工作区

网络环境

安装过程需访问 npm 官方注册表（registry.npmjs.org）和 Anthropic API（api.anthropic.com）。若网络需使用代理，请确保 npm 和终端层面的 HTTP 代理配置正确。Claude Code 在网络请求上遵循系统代理设置，不提供额外的代理参数。

安装步骤

以下步骤基于官方推荐流程，并标注了每个环节最常见的踩坑点。请按顺序执行，不要跳过前一步直接操作后一步。

步骤一：确认 Node.js 版本

使用 node -v 检查当前版本。若版本低于 18，或为奇数版本（如 19、21），则需先升级。

版本选择细节： 官方在 2025 年 7 月的说明中强调，Node.js 修复了 npm 安装过程中的关键依赖问题，因此推荐使用 Node.js 18 LTS 或 20 LTS。Node.js 22 虽是偶数版本，但当时尚未完成兼容测试。若你使用 Node.js 22 且安装失败，降级到 20 是最快的解决方案。

升级 Node.js 的最佳方式是使用 nvm（Node Version Manager）：

# 安装 nvm（如尚未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重新加载 shell 配置
source ~/.bashrc
# 安装并切换到 Node.js 20
nvm install 20
nvm use 20

安装完成后，再次运行 node -v 确认版本。建议新开一个终端窗口，确保 PATH 已更新。

步骤二：通过 npm 全局安装 claude-code

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

该命令会将 claude 可执行文件安装到 npm 的全局 bin 目录。安装过程需几十秒，具体时间视网络状况而定。

安装后验证： 在 macOS/Linux 上运行 which claude，或查看 npm 全局 bin 路径。若返回 not found，说明 npm 的全局 bin 目录未包含在系统 PATH 中。可通过 npm config get prefix 查看 npm 全局路径，然后将该路径下的 bin 子目录加入 $PATH。

在 macOS 上，默认路径通常为 /usr/local/bin，但若使用 nvm 安装 Node.js，全局 bin 路径可能在 ~/.nvm/versions/node/v20.x.x/bin/。将以下内容添加到 ~/.bashrc 或 ~/.zshrc 即可解决：

export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

步骤三：获取并配置 API 密钥

Claude Code 需连接到 Anthropic API 才能运行，因此必须拥有有效 API 密钥。

1. 登录 Anthropic Console，在 API Keys 页面创建密钥。
2. 密钥创建后仅显示一次，请立即复制并安全保存。
3. 配置环境变量：

export ANTHROPIC_API_KEY="sk-ant-你的密钥"

为使该设置持久生效，请将上述 export 语句添加到 ~/.bashrc、~/.zshrc 或 ~/.profile 中。

不推荐的做法： 直接在终端中粘贴密钥并执行命令，这会遗留在 shell 历史中。若使用共享设备，务必清除历史记录（history -c）。

步骤四：启动 Claude Code 并完成首次认证

在已配置 API 密钥的终端中，进入你的项目目录，然后运行：

claude

首次启动时，Claude Code 会提示你授权。若终端中已设置 ANTHROPIC_API_KEY 环境变量，它会自动读取并跳过交互式输入；否则，系统会提示你输入密钥。

启动后的行为： Claude Code 会扫描当前目录，通过分析 package.json、requirements.txt、go.mod 等文件来检测项目语言和框架，然后显示一个交互式命令行界面。此时，你即可直接在终端中提问，例如：

• "解释这个仓库的主要架构"
• "为 src/functions.ts 中的 createUser 函数编写单元测试"
• "帮我优化这条 SQL 查询的性能"

步骤五（可选）：配置编辑器集成

Claude Code 作为独立命令行工具运行，不与特定编辑器绑定。但它能读取当前项目中的文件，因此配合 VS Code 的终端面板使用效果更佳：在 VS Code 中按 Ctrl+（反引号）打开内置终端，然后运行 claude。如此一来，Claude Code 可直接访问当前工作区中的所有文件，你无需在编辑器和终端之间频繁切换。

验证检查

完成安装和首次启动后，通过以下检查确认一切正常。

检查 1：版本信息

claude --version

该命令会输出当前安装的版本号。若显示错误或为空白，则说明安装存在问题。

检查 2：能否正常回答

在 claude 交互界面中输入一个简单的编程问题，例如：

用 JavaScript 写一个函数，将驼峰命名转换为短横线命名

Claude Code 应输出代码并附上说明。若回复中包含系统指令执行（如修改文件、运行命令等），说明它已获得工作区权限，这属正常行为。

检查 3：网络与 API 连通性

若启动 claude 后长时间卡在 "Connecting..." 或直接报网络错误，请检查 API 密钥是否有效及网络是否可达：

curl -s -H "x-api-key: $ANTHROPIC_API_KEY" https://api.anthropic.com/v1/models | head -5

若返回 JSON 数据，说明网络和密钥均正常。若返回 401 或 403，则密钥无效或已过期。

常见问题排查

新手在安装配置过程中最容易遇到以下三个问题，下面逐一说明排查方法及正确处理顺序。

卡点 1：npm install 失败，权限错误

现象： 运行 npm install -g 时提示 EACCES: permission denied。

原因： 使用了系统安装的 Node.js（如通过 Homebrew 或系统包管理器），npm 全局目录位于受保护的 /usr/local 路径下。

正确做法： 避免使用 sudo npm install -g，这会导致后续权限混乱。推荐改用 nvm 管理的 Node.js，这样全局包会安装到用户目录下，不会触发权限问题。

若不方便使用 nvm，也可修改 npm 的全局前缀：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后将 ~/.npm-global/bin 添加到 PATH 中

卡点 2：启动 claude 后显示 "command not found"

现象： 安装成功后，关闭终端再打开，运行 claude 时提示找不到命令。

原因： npm 全局 bin 路径未添加到 shell 的 PATH 环境变量中。终端每次启动时读取的配置文件可能不同（如 ~/.bashrc、~/.zshrc 或 ~/.profile），export 语句可能被放在了错误的文件中，或者添加后未重新加载