第二章：环境搭建与安装

2.1 三种使用方式：如何选择

接触 Claude 生态时，你会遇到三个容易混淆的产品：Claude Code CLI、Claude Code VS Code 扩展、Claude Desktop。它们的定位和能力差别很大：

对比项	Claude Code CLI	Claude Code VS Code 扩展	Claude Desktop
运行环境	终端 / Terminal	VS Code 编辑器内	独立桌面应用
操作方式	纯键盘，自然语言输入指令	图形界面，侧边栏对话	图形界面，对话窗口
登录方式	API Key（写入 `settings.json`）或 `/login` 登录 Claude 账号订阅	与 CLI 共用同一套认证体系	仅支持 Claude.ai 订阅账号，不支持 API Key
优势	Agent 通用语言，可被其他 Agent 和脚本调用集成	与编辑器深度融合，无需切换窗口	开箱即用，无需安装配置
适合人群	熟悉终端操作、追求效率的开发者和产品经理	更习惯图形界面的专业用户	不写代码、需要随时和 AI 对话的普通用户
上下文感知	自动感知当前目录下的整个项目	自动感知 VS Code 打开的工作区	不主动感知本地项目，需要手动上传文件或通过 MCP 接入

本教程的选择

本教程以 Claude Code CLI 方式为主进行讲解。CLI 是 Claude Code 的原生形态，功能最完整，也是官方文档的主要介绍方式。掌握 CLI 后，VS Code 扩展的使用自然水到渠成。

为什么产品经理也需要熟悉 CLI？ 在 Agent 时代，CLI 是 Agent 的通用语言。设计一款面向 Agent 时代的软件，支持 CLI 能力不再是"可选项"，而是"必选项"。其他 Agent（如 OpenClaw、CI/CD 系统、自动化脚本等）都可以通过 CLI 直接调用和集成 Claude Code。作为产品经理，理解 CLI 的使用方式能让你：

更好地设计 Agent 时代的交互范式
理解 Agent 之间的协作和集成方式
在与技术团队沟通时，对 AI 能力的边界和可能性有更准确的判断

2.2 安装 Claude Code

macOS

推荐方式：使用 Homebrew 安装

bash

# 如果还没有安装 Homebrew，先安装（国内镜像源）
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

# 安装 Claude Code
brew install --cask claude-code

备选方式：官方安装脚本

bash

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

Windows

方法一：使用 WinGet（推荐）

powershell

winget install Anthropic.ClaudeCode

方法二：PowerShell 安装脚本

powershell

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

方法三：CMD 安装脚本

cmd

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Linux / WSL

bash

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

备选：通过 npm 安装

如果以上方式不适用于你的环境，也可以通过 Node.js 的 npm 安装：

bash

# 可选：使用国内镜像源加速
npm config set registry https://registry.npmmirror.com

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

验证安装

安装完成后，打开一个新的终端窗口，运行：

bash

claude --version

看到版本号输出即安装成功。

2.3 推荐安装的开发环境

除了 Claude Code 本身，还建议安装以下工具。

Git（强依赖）

Git 是版本管理工具。Claude Code 会通过 Git 理解项目历史、创建提交、管理分支。

Node.js

Node.js 是 JavaScript 的运行环境，Claude Code 生成前端项目、运行构建工具时需要用到。

macOS（Homebrew）：

bash

brew install node

Windows： 前往 https://nodejs.org/zh-cn 下载 LTS 版本安装包，双击安装即可。

验证：

bash

node --version   # 建议 18+
npm --version

Python

Python 是数据分析、脚本编写的首选语言。让 Claude Code 帮你做数据分析、跑自动化脚本时，都需要 Python 环境。

macOS（Homebrew）：

bash

brew install python

Windows： 前往 https://www.python.org/downloads 下载安装包。安装时务必勾选 "Add Python to PATH"。

验证：

bash

python --version   # 或 python3 --version

macOS（Homebrew）：

bash

brew install git

Windows： 前往 https://git-scm.com/download/win 下载安装。安装时建议勾选 "Git Bash Here"，这会提供一个类 Unix 的终端环境。

验证：

bash

git --version

为什么要安装这些？

Claude Code 在执行任务时，会优先使用本机已安装的运行环境。例如，当你让它写一个脚本分析数据，如果本机有Python环境，它会使用python进行编写；如果没有python但有nodeJs，它可能会退而求其次编写nodeJs脚本。提前安装必要工具环境能让Claude Code默认使用最优解，避免绕远路。

2.4 Windows 用户特别建议

升级 Windows Terminal

如果你使用的是 Windows 10，自带的命令提示符（CMD）和 PowerShell 窗口体验较差，建议安装 Windows Terminal：

powershell

winget install Microsoft.WindowsTerminal

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

Windows Terminal 相比自带终端的优势：

多标签页：同时打开多个终端，方便在不同项目间切换
GPU 渲染：更流畅的文字显示，支持丰富的 Unicode 字符
更好的颜色支持：Claude Code 的输出会更美观、更易读
分屏功能：一边跑 Claude Code，一边看项目文件

Windows 11 用户

Windows 11 已经内置了 Windows Terminal 作为默认终端，无需额外安装。

终端	推荐度	说明
Windows Terminal	⭐⭐ 强烈推荐	微软官方现代终端
WSL2	⭐⭐ 推荐	完整的 Linux 环境，支持 tmux
Git Bash	⭐ 推荐	安装 Git 后自带，类 Unix 体验
PowerShell	可用	Windows 自带
CMD	不推荐	功能有限，兼容性问题多

2.5 获取与配置 API Key

Claude Code 通过 Anthropic API 调用 AI 模型，需要一个 API Key。

获取 API Key

访问 Anthropic Console 注册 / 登录
进入 API Keys 页面，点击 Create Key
给 Key 起一个名称（如 claude-code-workshop）并创建
立即复制并保存——Key 只会显示一次

安全提醒

绝对不要 把 API Key 分享给别人、提交到代码仓库、或发布到网上。如果 Key 泄露，请立即在 Console 中删除并重新创建。

通过 settings.json 配置 API Key

Claude Code 推荐通过 settings.json 配置文件来管理 API Key 和其他配置。这种方式相比设置系统环境变量更清晰、更可移植。

步骤 1：创建用户级配置文件

打开（或创建）~/.claude/settings.json 文件：

bash

# macOS / Linux
~/.claude/settings.json

# Windows（PowerShell）
C:\Users\<你的用户名>\.claude\settings.json

步骤 2：写入 API Key

用编辑器打开该文件，写入以下内容：

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxx你的Key"
  }
}

env 字段中声明的变量会被 Claude Code 在每次启动会话时自动加载，效果等同于设置系统环境变量，但只对 Claude Code 生效，不会污染其他程序。

步骤 3：使用第三方 API 服务（可选）

如果你使用 API 代理、企业网关或第三方兼容服务，把 ANTHROPIC_API_KEY 改成 ANTHROPIC_AUTH_TOKEN，并设置 ANTHROPIC_BASE_URL：

json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的-token",
    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com"
  }
}

变量	说明
`ANTHROPIC_API_KEY`	官方 API Key，用于直连 Anthropic
`ANTHROPIC_AUTH_TOKEN`	自定义认证 token，会以 `Bearer` 方式发送，常用于代理服务
`ANTHROPIC_BASE_URL`	自定义 API 端点，用于代理或网关路由

配置文件位置

用户级：~/.claude/settings.json（对所有项目生效，推荐用于 API Key）
项目级：.claude/settings.json（提交到 Git，团队共享）
本地级：.claude/settings.local.json（不提交，个人覆盖）

API Key 这类敏感信息请放在用户级，不要写入项目级文件，避免误提交到仓库。

2.6 settings.json 详细配置

settings.json 是 Claude Code 的核心配置文件，支持远不止 API Key 的设置。掌握它可以让 Claude Code 完全适配你的工作习惯。

配置作用域与优先级

Claude Code 通过分层作用域来管理配置，优先级从高到低：

作用域	文件位置	适用范围	Git 共享
Managed	系统目录（IT 部署）	所有用户	是（IT 部署）
Local	`.claude/settings.local.json`	当前项目，仅自己	否（自动 gitignore）
Project	`.claude/settings.json`	当前项目，所有协作者	是
User	`~/.claude/settings.json`	所有项目	否

当同一项配置出现在多个作用域中，优先级高的会覆盖低的。

常用配置项

env：环境变量

最常用的配置项，所有 Claude Code 支持的环境变量都可以在这里设置：

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxx",
    "HTTPS_PROXY": "http://your-proxy:port",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Id: my-team"
  }
}

model：默认模型

指定 Claude Code 启动时默认使用的模型：

json

{
  "model": "claude-sonnet-4-6"
}

也可以通过环境变量分别配置三个等级的模型：

json

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

permissions：权限规则

精细控制 Claude Code 可以执行哪些操作（详见第 9 章）：

json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

apiKeyHelper：动态获取 API Key

如果你的 API Key 需要动态生成（例如临时凭证、企业 SSO），可以指定一个脚本来动态返回：

json

{
  "apiKeyHelper": "/Users/me/scripts/get-claude-key.sh"
}

includeCoAuthoredBy：Git 提交署名

控制 Claude Code 创建 Git 提交时是否添加 Co-Authored-By: Claude 标记：

json

{
  "includeCoAuthoredBy": false
}

完整示例

一个比较完整的用户级 settings.json 示例：

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxx",
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  },
  "model": "claude-sonnet-4-6",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "includeCoAuthoredBy": false
}

关于 $schema 字段

$schema 行指向官方 JSON Schema，添加后 VS Code、Cursor 等编辑器会自动提供字段补全和校验，可以避免拼写错误和格式问题。强烈建议加上。

在 Claude Code 中查看与修改

启动 Claude Code 后，可以通过 /config 命令打开图形化的设置界面，查看当前配置和修改常用项。手动编辑 settings.json 适合精细配置和团队共享，/config 命令则更适合临时调整。

2.7 首次启动

打开终端，进入你想让 Claude Code 工作的项目目录，运行：

bash

claude

首次启动时，如果已配置好 API Key，你会看到欢迎界面。输入一句话测试：

你好，请做一下自我介绍

如果 Claude Code 正常回复，说明安装配置全部成功。

如果已经开通了claude code官方账号，可以在 Claude Code 中输入 /login 按提示完成认证。

2.8 更新 Claude Code

Claude Code 更新频繁，建议定期更新。

bash

# 原生安装器（支持自动更新）
claude update

# Homebrew
brew upgrade --cask claude-code

# npm 方式
npm update -g @anthropic-ai/claude-code

2.9 本章小结

步骤	内容	要点
选择方式	CLI vs VS Code 扩展	本教程以 CLI 为主
安装 Claude Code	Homebrew / WinGet / 官方脚本 / npm	选一种即可
安装开发环境	Node.js、Python、Git	Claude Code 会优先使用本机环境执行任务
配置 API Key	写入 `~/.claude/settings.json`	通过 `env` 字段管理
验证	`claude --version` + 对话测试	确认可以正常使用

快速参考

bash

# macOS 一键安装（Homebrew）
brew install --cask claude-code
brew install node python git

# Windows 一键安装（WinGet）
winget install Anthropic.ClaudeCode
winget install Microsoft.WindowsTerminal

最简 ~/.claude/settings.json：

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxx"
  }
}

bash

# 启动
claude

# 更新
claude update

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

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

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

2.1 三种使用方式：如何选择 ​

2.2 安装 Claude Code ​

macOS ​

Windows ​

Linux / WSL ​

备选：通过 npm 安装 ​

验证安装 ​

2.3 推荐安装的开发环境 ​

Git（强依赖） ​

Node.js ​

Python ​

2.4 Windows 用户特别建议 ​

升级 Windows Terminal ​

推荐的终端选择 ​

2.5 获取与配置 API Key ​

获取 API Key ​

通过 settings.json 配置 API Key ​

2.6 settings.json 详细配置 ​

配置作用域与优先级 ​

常用配置项 ​

完整示例 ​

在 Claude Code 中查看与修改 ​

2.7 首次启动 ​

2.8 更新 Claude Code ​

2.9 本章小结 ​

第二章：环境搭建与安装

2.1 三种使用方式：如何选择

2.2 安装 Claude Code

macOS

Windows

Linux / WSL

备选：通过 npm 安装

验证安装

2.3 推荐安装的开发环境

Git（强依赖）

Node.js

Python

2.4 Windows 用户特别建议

升级 Windows Terminal

推荐的终端选择

2.5 获取与配置 API Key

获取 API Key

通过 settings.json 配置 API Key

2.6 settings.json 详细配置

配置作用域与优先级

常用配置项

完整示例

在 Claude Code 中查看与修改

2.7 首次启动

2.8 更新 Claude Code

2.9 本章小结