城市军团AI提效工作坊

Appearance

第二章：环境搭建与安装 ​

2.1 安装概览 ​

在开始使用 Claude Code 之前，我们需要完成以下准备工作：

安装流程（推荐：原生安装器）：

  ① 使用原生安装器安装 Claude Code（无需 Node.js）
       ↓
  ② 获取 Anthropic API Key
       ↓
  ③ 首次启动与认证
       ↓
  ④ 验证安装成功
安装流程（备选：npm 方式）：

  ① 安装 Node.js 18+
       ↓
  ② 用 npm 安装 Claude Code
       ↓
  ③ 获取 Anthropic API Key
       ↓
  ④ 首次启动与认证
       ↓
  ⑤ 验证安装成功

整个过程大约需要 10-30 分钟。让我们一步一步来。

操作系统

本教程同时覆盖 Windows、macOS 和 Linux 三个平台的安装步骤。请根据你的操作系统选择对应的指引。

2.2 第一步：安装 Claude Code（推荐：原生安装器） ​

Claude Code 提供了原生安装器，无需预先安装 Node.js，是最简单的安装方式。

macOS / Linux ​

打开终端，运行以下一行命令即可完成安装：

bash
curl -fsSL https://claude.ai/install.sh | bash

安装脚本会自动下载并配置 Claude Code。安装完成后，你可以直接在终端中使用 claude 命令。

Windows ​

方法一：使用 WinGet（推荐）

打开 PowerShell 或 Windows Terminal，运行：

powershell
winget install Anthropic.Claude

方法二：使用 PowerShell 安装脚本

powershell
irm https://claude.ai/install.ps1 | iex

原生安装器的优势

  • 无需安装 Node.js 或任何其他依赖
  • 安装过程更简单、更快
  • 支持自动更新（claude update）
  • 这是 Anthropic 官方推荐的安装方式

安装完成后，可以直接跳到 2.4 获取 API Key 继续配置。

2.3 备选方式：通过 npm 安装 ​

如果你更熟悉 Node.js 生态，或者原生安装器不适用于你的环境，也可以通过 npm 安装 Claude Code。

2.3.1 安装 Node.js ​

使用 npm 方式安装 Claude Code 需要先安装 Node.js。

什么是 Node.js ​

简单说，Node.js 是一个让 JavaScript 能在电脑上运行的环境。通过 npm 方式安装的 Claude Code 需要 Node.js 来运行。

版本要求

npm 安装方式需要 Node.js 18 或更高版本。建议安装最新的 LTS（长期支持）版本。如果你使用原生安装器，则不需要安装 Node.js。

Windows 安装 Node.js ​

方法一：官网下载安装包（推荐新手使用）

  1. 打开浏览器，访问 Node.js 官网：https://nodejs.org
  2. 点击 LTS（长期支持版）下载按钮
  3. 下载完成后，双击安装包运行
  4. 安装向导中一直点击 Next（默认选项即可）
  5. 安装完成后点击 Finish

方法二：使用 winget 命令安装

如果你已经熟悉命令行，可以打开 PowerShell 或 Windows Terminal，运行：

powershell
winget install OpenJS.NodeJS.LTS

方法三：使用 fnm（Fast Node Manager）

fnm 是一个 Node.js 版本管理工具，适合需要管理多个 Node.js 版本的用户：

powershell
# 安装 fnm
winget install Schniz.fnm

# 安装 Node.js LTS 版本
fnm install --lts

# 使用该版本
fnm use lts-latest

macOS 安装 Node.js ​

方法一：官网下载安装包

  1. 访问 https://nodejs.org
  2. 下载 macOS 版的 LTS 安装包
  3. 双击 .pkg 文件，按提示完成安装

方法二：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，运行：

bash
brew install node@22

方法三：使用 fnm

bash
# 安装 fnm
brew install fnm

# 添加到 shell 配置（zsh）
echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
source ~/.zshrc

# 安装 Node.js
fnm install --lts
fnm use lts-latest

Linux 安装 Node.js ​

Ubuntu / Debian：

bash
# 使用 NodeSource 安装脚本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

使用 fnm（推荐，所有发行版通用）：

bash
# 安装 fnm
curl -fsSL https://fnm.vercel.app/install | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js
fnm install --lts
fnm use lts-latest

验证 Node.js 安装 ​

安装完成后，打开一个新的终端窗口（这一步很重要！），运行以下命令验证：

bash
node --version

你应该看到类似这样的输出：

v22.11.0

同时验证 npm（Node.js 的包管理器）是否可用：

bash
npm --version

你应该看到类似这样的输出：

10.9.0

版本检查

请确保 Node.js 版本号是 18.0.0 或更高。如果版本太低，请重新安装最新的 LTS 版本。

常见问题：输入命令后提示"不是内部或外部命令"

这通常是因为 Node.js 没有被添加到系统的 PATH 环境变量中。解决方法：

  1. Windows：重新运行 Node.js 安装程序，确保勾选了"Add to PATH"选项
  2. macOS/Linux：关闭终端窗口，重新打开一个新窗口再试
  3. 如果问题仍然存在，尝试重启电脑

2.3.2 使用 npm 安装 Claude Code ​

Node.js 安装好之后，就可以通过 npm 安装 Claude Code。

使用 npm 安装 ​

在终端中运行以下命令：

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

让我们来解释一下这条命令的各个部分：

部分含义
npmNode.js 的包管理器（Node Package Manager）
install安装一个包
-g全局安装（在任何目录下都可以使用）
@anthropic-ai/claude-codeClaude Code 的包名

安装过程通常需要 1-2 分钟，取决于你的网络速度。

安装过程中的输出 ​

正常情况下，你会看到类似这样的输出：

npm warn deprecated some-package@x.x.x: ...
added 150 packages in 30s

关于 warn 信息

安装过程中看到 npm warn 是正常的，这些是一些依赖包的提示信息，不影响使用。只要最后显示 added xxx packages 就表示安装成功了。

验证 Claude Code 安装 ​

运行以下命令验证安装：

bash
claude --version

你应该看到类似这样的输出：

1.0.16 (Claude Code)

如果能看到版本号，恭喜你，Claude Code 安装成功了！

macOS/Linux 权限问题

如果在 macOS 或 Linux 上安装时遇到权限错误（EACCES 错误），不要使用 sudo npm install -g。正确的做法是修复 npm 的权限：

bash
# 创建全局安装目录
mkdir -p ~/.npm-global

# 配置 npm 使用这个目录
npm config set prefix '~/.npm-global'

# 添加到 PATH（zsh）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 然后重新安装
npm install -g @anthropic-ai/claude-code

如果使用 bash，把 ~/.zshrc 替换为 ~/.bashrc。

常见问题：npm install 速度很慢

如果你在中国大陆，npm 下载速度可能较慢。你可以使用镜像源加速：

bash
# 使用淘宝镜像（临时，仅本次安装生效）
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

或者全局设置镜像源：

bash
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

2.4 第二步：获取 API Key ​

Claude Code 需要通过 Anthropic 的 API 来调用 AI 模型。为此，你需要一个 API Key。

什么是 API Key ​

API Key 就像是一把钥匙，用来验证你的身份并允许你使用 Anthropic 的 AI 服务。每个 API Key 和你的 Anthropic 账户绑定，API 用量和费用也会计入你的账户。

注册 Anthropic Console 账号 ​

  1. 打开浏览器，访问 https://console.anthropic.com
  2. 点击 Sign Up 注册新账号（或 Log In 登录已有账号）
  3. 按照提示完成注册流程

创建 API Key ​

  1. 登录后，点击左侧菜单的 API Keys
  2. 点击 Create Key 按钮
  3. 给你的 Key 起一个名字，比如 claude-code-workshop
  4. 点击 Create Key
  5. 重要： 复制并妥善保存你的 API Key

安全提醒

API Key 只会在创建时显示一次！请立即复制并保存到安全的地方（如密码管理器）。如果丢失了，你需要创建一个新的 Key。

绝对不要 把 API Key 分享给别人、提交到代码仓库、或发布到网上。

设置 API Key ​

你可以通过环境变量来设置 API Key。

Windows（PowerShell）：

powershell
# 临时设置（仅当前终端窗口有效）
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxx你的Key"

# 永久设置
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-xxxxx你的Key", "User")

Windows（Git Bash / MSYS2）：

bash
# 临时设置
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx你的Key"

# 永久设置（添加到配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx你的Key"' >> ~/.bashrc
source ~/.bashrc

macOS / Linux：

bash
# 临时设置（仅当前终端窗口有效）
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx你的Key"

# 永久设置
# zsh 用户（macOS 默认）：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx你的Key"' >> ~/.zshrc
source ~/.zshrc

# bash 用户：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx你的Key"' >> ~/.bashrc
source ~/.bashrc

建议使用永久设置

临时设置在关闭终端后就失效了，每次都需要重新设置。建议使用永久设置的方法，这样只需设置一次。

充值 API 额度 ​

新注册的 Anthropic 账户可能有免费额度。如果需要充值：

  1. 在 Anthropic Console 中进入 Settings > Billing
  2. 添加支付方式
  3. 设置预算和自动充值规则

费用参考

Claude Code 的费用取决于你的使用量。一般来说：

  • 简单的问答：每次约 $0.01-0.05
  • 复杂的代码分析：每次约 $0.10-0.50
  • 大型项目操作：每次约 $0.50-2.00

对于学习阶段，准备 $5-10 的额度通常就够了。你可以在 Console 中设置用量告警，避免超出预算。

2.5 第三步：首次启动 ​

一切准备就绪，让我们启动 Claude Code！

启动命令 ​

打开终端，进入任意一个你想让 Claude Code 工作的目录，然后运行：

bash
claude

就是这么简单——一个 claude 命令就够了。

首次启动流程 ​

第一次启动 Claude Code 时，你会看到以下流程：

$ claude

╭──────────────────────────────────────╮
│ ✻ Welcome to Claude Code!            │
│                                      │
│ /help for help, /status for status   │
╰──────────────────────────────────────╯

 ✻ You haven't authenticated yet.

 To get started, run /login

如果你还没有通过环境变量设置 API Key，Claude Code 会引导你完成认证。

认证方式 ​

Claude Code 支持多种认证方式：

方式一：环境变量（推荐，上一步已设置）

如果你已经按照上一步设置了 ANTHROPIC_API_KEY 环境变量，Claude Code 会自动使用它，无需额外操作。

方式二：交互式登录

如果没有设置环境变量，你可以在 Claude Code 中输入：

/login

然后按照提示完成认证。

验证连接 ​

启动后，你可以输入一个简单的问题来测试：

你好，请做一下自我介绍

如果 Claude Code 正常回复了，说明一切配置成功！你应该会看到类似这样的响应：

你好！我是 Claude，Anthropic 开发的 AI 助手。我正在通过 Claude Code
运行，这意味着我可以访问你的文件系统，执行命令，帮助你完成各种开发任务。

我可以帮你：
- 编写和修改代码
- 分析项目结构
- 调试问题
- 生成文档
...

有什么我可以帮你的吗？

检查费用

首次测试后，可以在 Anthropic Console 的 Usage 页面查看 API 用量，确认一切正常。

2.6 第四步：验证安装完整性 ​

让我们做一个完整的验证，确保所有组件都正常工作。

运行 /doctor 命令 ​

Claude Code 内置了一个诊断命令，可以帮你检查环境：

/doctor

这个命令会检查：

  • Node.js 版本是否满足要求
  • Claude Code 版本是否是最新的
  • API 连接是否正常
  • 权限设置是否正确

手动验证清单 ​

你也可以手动逐项检查：

bash
# 1. 检查 Node.js 版本（需要 18+）
node --version

# 2. 检查 npm 版本
npm --version

# 3. 检查 Claude Code 版本
claude --version

# 4. 检查 API Key 是否设置（应该显示 sk-ant... 开头的值）
# Windows PowerShell:
echo $env:ANTHROPIC_API_KEY
# macOS / Linux / Git Bash:
echo $ANTHROPIC_API_KEY

安全提示

在验证 API Key 时，注意不要在录屏或他人可见的情况下显示完整的 Key。

2.7 更新 Claude Code ​

Claude Code 更新频繁，建议定期更新到最新版本以获得最新功能和修复。

原生安装器方式更新（推荐） ​

如果你使用原生安装器安装的 Claude Code，更新非常简单：

bash
claude update

原生安装器还支持自动更新——Claude Code 会在后台自动检查并安装新版本，通常无需手动操作。

npm 方式更新 ​

如果你通过 npm 安装的 Claude Code：

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

检查是否有可用更新：

bash
npm outdated -g @anthropic-ai/claude-code

查看当前版本 ​

bash
claude --version

更新建议

Claude Code 的更新迭代非常快，经常会加入新功能和改进。使用原生安装器的用户通常会自动获取更新。使用 npm 安装的用户建议每周检查一次更新。

2.8 Windows 用户特别说明 ​

Windows 用户在使用 Claude Code 时需要注意一些特别事项。

推荐的终端 ​

Claude Code 推荐在以下终端中使用：

终端推荐度说明
Windows Terminal强烈推荐微软官方终端，支持多标签、GPU 渲染
Git Bash推荐安装 Git for Windows 时自带
WSL2推荐完整的 Linux 环境
PowerShell可用Windows 自带，兼容性良好
CMD（命令提示符）不推荐功能有限，可能遇到兼容问题

安装 Windows Terminal ​

如果你还没有安装 Windows Terminal：

powershell
winget install Microsoft.WindowsTerminal

或者从 Microsoft Store 搜索 "Windows Terminal" 安装。

安装 Git Bash ​

Git Bash 提供了类 Unix 的命令行环境，很多开发工具在这个环境下工作得更好：

  1. 访问 https://git-scm.com/download/win
  2. 下载并安装 Git for Windows
  3. 安装时勾选 "Git Bash Here" 选项

WSL2（Windows Subsystem for Linux） ​

如果你想获得最佳体验，可以考虑安装 WSL2：

powershell
# 在管理员权限的 PowerShell 中运行
wsl --install

安装完成后重启电脑，然后在 WSL2 的 Ubuntu 环境中安装 Node.js 和 Claude Code。

Windows 常见问题汇总

问题：安装时报错 "EPERM: operation not permitted"

  • 解决：以管理员身份运行终端，或修改 npm 全局安装路径

问题：claude 命令找不到

  • 解决：关闭终端窗口重新打开，或检查 npm 全局安装目录是否在 PATH 中
  • 检查方法：运行 npm config get prefix，确认输出的路径在你的 PATH 环境变量中

问题：Git Bash 中显示乱码

  • 解决：在 Git Bash 标题栏右键 > Options > Text > 选择 UTF-8

问题：API 连接超时

  • 解决：检查网络连接，确认能访问 api.anthropic.com
  • 如果有代理：设置 HTTPS_PROXY 环境变量

2.9 macOS 用户特别说明 ​

Homebrew 安装 ​

如果你还没有安装 Homebrew（macOS 的包管理器），先安装它：

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后就可以用 Homebrew 安装 Node.js：

bash
brew install node@22

macOS 权限问题 ​

macOS 可能会阻止从终端运行未签名的程序。如果遇到安全提示：

  1. 打开 系统偏好设置 > 安全性与隐私
  2. 在 通用 标签下，点击 仍要打开

2.10 配置网络代理（可选） ​

如果你的网络环境需要代理才能访问外网，需要进行额外配置。

设置代理环境变量 ​

bash
# HTTP 代理
export HTTP_PROXY="http://your-proxy:port"
export HTTPS_PROXY="http://your-proxy:port"

# 或 SOCKS5 代理
export ALL_PROXY="socks5://your-proxy:port"

npm 代理设置 ​

bash
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

公司网络

如果你在公司网络下使用，可能需要联系 IT 部门获取代理地址和端口信息。

2.11 本章小结 ​

恭喜！你已经完成了 Claude Code 的环境搭建。让我们回顾一下完成的步骤：

步骤内容状态
第一步安装 Claude Code（原生安装器或 npm）完成
第二步获取并配置 API Key完成
第三步首次启动验证完成
第四步验证安装完整性完成

快速参考卡片 ​

bash
# 安装 Claude Code（推荐：原生安装器）
# macOS / Linux:
curl -fsSL https://claude.ai/install.sh | bash
# Windows (WinGet):
# winget install Anthropic.Claude

# 安装 Claude Code（备选：npm 方式，需要 Node.js 18+）
npm install -g @anthropic-ai/claude-code

# 设置 API Key
export ANTHROPIC_API_KEY="your-key-here"

# 启动 Claude Code
claude

# 检查版本
claude --version

# 更新 Claude Code
claude update                              # 原生安装器
npm update -g @anthropic-ai/claude-code    # npm 方式
自我检查

在进入下一章之前，请确认以下几点：

  1. node --version 显示 18.0.0 或更高版本
  2. claude --version 显示版本号
  3. 启动 claude 后能正常对话
  4. 在 Anthropic Console 能看到 API 用量记录

如果以上任何一点有问题，请回到对应的步骤重新操作，或在工作坊中寻求帮助。

准备好了吗？让我们进入下一章，学习 Claude Code 的基础使用方法！

下一章：基础使用方法 ->