Claude Code零基础入门指南：手把手配置AI编程助手环境

你只需要准备好三样东西，就能开始使用 Claude Code 了。

1. 一台电脑：Windows 10/11、macOS 或 Linux 系统都可以。
2. Node.js (v22+)：这是 Claude Code 运行所必须的底层环境。
3. API Key：这是让 Claude Code 能够连接AI模型服务的“通行证”，可以来自 Anthropic 官方或其替代服务。

打个比方：Claude Code 相当于你的手机，Node.js 是手机操作系统，而 API Key 就是手机卡。三者缺一不可，你的“手机”才能联网工作。

术语速查（记住这6个词就够了）

术语	通俗解释
终端/Terminal	一个可以输入命令来控制电脑的窗口。
CLI	命令行工具，就是在终端里运行的软件，Claude Code 就是其中之一。
Node.js	Claude Code 依赖的运行环境，必须安装。
npm	Node.js 自带的“应用商店”，我们用它来安装 Claude Code。
API Key	一串用来访问AI模型服务的密码字符串，务必妥善保管。
环境变量	将 API Key 安全地存储在系统中的方式，避免直接写在代码里。

快速导航（建议按此顺序操作）

请按照以下步骤，一步步完成环境搭建：

✅ 第 1 部分：安装 Node.js（约20-40分钟）
✅ 第 2 部分：准备 API Key（约10分钟）
✅ 第 3 部分：配置环境变量（约5分钟）
✅ 第 4 部分：安装 Claude Code（约10分钟）
✅ 第 5 部分：启动与验证（约10-15分钟）

1. 安装 Node.js（必须步骤）

1.1 Windows 用户（推荐使用官网安装包）

步骤 1：下载安装包

1. 打开浏览器。
2. 访问 Node.js 官网。
3. 下载 LTS（长期支持版） 的 Windows 安装包（通常是 .msi 文件）。

步骤 2：运行安装

1. 双击下载的 .msi 安装包。
2. 在安装向导中一路点击 “Next”。
3. 关键步骤：在安装过程中，务必勾选 Add to PATH（添加到环境变量） 这个选项。
4. 安装完成后点击 “Finish”。

步骤 3：验证安装是否成功

1. 打开终端：
   • 按下 Win键 + R。
   • 输入 PowerShell，然后回车。
2. 在打开的 PowerShell 窗口中，逐行输入以下两条命令，每输入一条就按一次回车：

node -v
npm -v

看到什么算成功？

• node -v 输出类似 v22.x.x 或更高的版本号。
• npm -v 输出类似 10.x.x 或更高的版本号。

如果提示“不是内部或外部命令”怎么办？

• 首先，关闭终端窗口并重新打开再试一次。
• 如果还不行，重启电脑后重试，这通常能让环境变量生效。

提示：如果从官网下载速度太慢，可以尝试使用国内的镜像源，例如 清华镜像站。

1.2 macOS 用户（推荐使用 Homebrew）

如果你不了解 Homebrew 也没关系，跟着做就行。

步骤 1：打开终端

• 按下 Command(⌘) + 空格。
• 输入 Terminal（终端），然后回车。

步骤 2：检查是否已安装 Homebrew

brew -v

• 如果显示了版本号，继续下一步。
• 如果提示“找不到命令”，你需要先安装 Homebrew（网上搜索官方安装命令，通常只需一行命令）。

步骤 3：安装 Node.js 22

brew install node@22
brew link node@22
node -v
npm -v

看到 v22.x.x 和 10.x.x 就表示安装成功了。

1.3 Linux 用户（以 Ubuntu/Debian 为例）

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

2. 准备 API Key（必须步骤）

Claude Code 需要连接AI模型服务才能工作。你有两个主要选择：

2.1 方案 A：使用 Anthropic 官方 Key

1. 注册并登录 Anthropic Console。
2. 在 API Keys 页面，创建一个新的 Key。请注意：这个 Key 只显示一次，务必立即复制并妥善保存！

安全保存建议：

• 在电脑上新建一个文本文件，例如 anthropic-key.txt。
• 将复制的 API Key 粘贴进去并保存。
• 切勿将 Key 截图分享到群聊、朋友圈或任何公开平台。

2.2 方案 B：使用国内替代服务（可选）

如果你的网络访问 Anthropic 服务不稳定，可以考虑使用国内提供的模型中转服务（例如 GML、MinMax等）。核心目标是：获得一串可用的 API Key，并知道如何配置给 Claude Code 使用。

注意：不同平台对 API Key 的命名或所需配置的环境变量名称可能不同，请以服务商提供的文档为准。

3. 配置环境变量（推荐的安全做法）

为了避免在代码中硬编码 API Key，我们将其设置为环境变量。

3.1 Windows（在 PowerShell 中配置）

1. 打开 PowerShell。
2. 执行以下命令（将 你的Key 替换成你真实的 API Key）：

   [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', ‘你的Key’， ‘User’)

3. 关闭当前的 PowerShell 窗口，然后重新打开一个新的。
4. 验证配置是否成功：

   $env:ANTHROPIC_API_KEY

   如果能看到你设置的 Key（非空内容），则说明配置成功。

3.2 macOS / Linux

将下面这行代码添加到你的 Shell 配置文件中（如果你用 zsh，通常是 ~/.zshrc；如果用 bash，通常是 ~/.bashrc）。

export ANTHROPIC_API_KEY=“你的Key”

保存文件后，执行以下命令使配置生效并验证：

source ~/.zshrc   # 或 source ~/.bashrc
echo $ANTHROPIC_API_KEY

4. 安装 Claude Code（通过 npm 全局安装）

打开终端，执行以下安装命令：

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

安装完成后，验证安装是否成功：

claude --version
claude --help

如果能看到版本号以及帮助信息，就说明 Claude Code 安装成功了。

5. 首次启动与功能验证

5.1 启动 Claude Code

在终端任意目录下，直接输入 claude 并回车：

claude

你会看到一个欢迎界面，然后出现 You: 或 > 这样的输入提示符，这表示 Claude Code 已成功启动。

5.2 快速功能验证（1分钟测试）

为了确保 API Key、网络和 Claude Code 本身都工作正常，我们做一个快速测试：

claude -p “请用一句话介绍你自己”

如果 Claude Code 能返回一段清晰的自我介绍，那么恭喜你，基础环境已经全部打通了！

5.3 Hello World 项目实战

现在，让我们验证 Claude Code 的核心功能：它不仅能回答问题，还能直接创建文件和生成代码。

步骤 1：创建并进入项目目录

• Windows (PowerShell) / macOS / Linux：

  mkdir claude-hello-world
  cd claude-hello-world

  

步骤 2：指令 Claude Code 生成项目文件
在 claude-hello-world 目录下，执行：

claude -p “请创建一个 Python Hello World 项目：生成 hello.py 打印 ‘Hello, Claude Code!’，再生成 README.md 和 .gitignore（Python 标准）”

Claude Code 会开始工作，并最终告诉你项目已创建完成。

步骤 3：检查生成的文件

• Windows：在终端输入 dir
• macOS/Linux：在终端输入 ls

你应该能看到 hello.py、README.md 和 .gitignore 这三个文件。

步骤 4：运行生成的代码

python hello.py

如果终端成功打印出 Hello, Claude Code!，那么恭喜你，你已经完整跑通了 Claude Code 从环境搭建到实际编码辅助的整个流程！

常见问题与解决方法

Q1: claude: command not found

• 原因：Claude Code 未安装成功，或系统 PATH 未生效。
• 解决：
  1. 关闭终端重新打开。
  2. 重新运行安装命令：npm install -g @anthropic-ai/claude-code。
  3. 再次执行 claude --version 验证。

Q2: Windows PowerShell 提示“禁止运行脚本”

• 症状：运行 claude 时报错，提示 .ps1 脚本无法执行。
• 解决：在 PowerShell（管理员身份运行）中执行以下命令修改执行策略：

  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Q3: node 不是内部或外部命令

• 原因：Node.js 未安装或 PATH 环境变量未正确设置。
• 解决：
  1. 关闭终端并重新打开，或直接重启电脑。
  2. 若仍无效，请重新安装 Node.js，并务必确认勾选了 Add to PATH 选项。

Q4: API key not found

• 原因：环境变量配置有误或未生效。
• 解决：
  • Windows：运行 $env:ANTHROPIC_API_KEY 查看是否为空。
  • macOS/Linux：运行 echo $ANTHROPIC_API_KEY 查看是否为空。
  • 如果为空，请返回 第 3 部分 重新配置环境变量。

Q5: npm 下载安装包太慢或超时

• 原因：网络连接问题，在国内较常见。
• 解决：将 npm 源切换为国内镜像（如淘宝源）。

  npm config set registry https://registry.npmmirror.com
  npm config get registry # 用于验证是否切换成功

最终检查清单

完成所有步骤后，请逐一核对以下项目，确保一切就绪：

• [ ] node -v 显示 v22 或更高版本。
• [ ] npm -v 显示 10.x 或更高版本。
• [ ] claude --version 能正常输出版本号。
• [ ] 环境变量 ANTHROPIC_API_KEY 能被正确读取（非空）。
• [ ] claude -p “...” 能收到 Claude 的回复。
• [ ] 在 claude-hello-world 目录下成功生成了 hello.py、README.md 和 .gitignore 文件。
• [ ] 运行 python hello.py 成功打印出 Hello， Claude Code!。

至此，你已经成功完成了 Claude Code 的零基础环境搭建。它不仅是你的代码助手，更能深度集成到你的工作流中，例如进行文件管理、Git操作等复杂的软件工程任务。如果在后续使用中遇到任何问题，欢迎到 云栈社区 的 Node.js 或 Python 板块与其他开发者交流，那里有丰富的 技术文档 和实战经验分享。

---

修订记录

• 2026-01-23：重写为零基础友好版本，强调最小可运行闭环。