在 macOS 上安装 Claude Code 的完整指南

文章目录

- 概述
- 前置要求
- 安装方法
- - 方法一：官方安装脚本（推荐）
  - [方法二：使用 npm 安装](#方法二：使用 npm 安装)
  - [方法二：使用 Homebrew（推荐）](#方法二：使用 Homebrew（推荐）)
- [获取和配置 API 密钥](#获取和配置 API 密钥)
- - [获取 API 密钥](#获取 API 密钥)
  - 配置认证
- 验证安装
- 基础使用
- - 简单对话
  - 文件处理
  - 管道操作
  - [启动 Claude Code](#启动 Claude Code)
  - 常用命令示例
  - 处理图片和截图
- 高级配置
- - 创建别名和函数
  - 配置不同的模型
- 最佳实践
- - 提供具体指令
  - 利用上下文
  - [有效的 Git 工作流](#有效的 Git 工作流)
- 安全最佳实践
- - [API 密钥安全](#API 密钥安全)
  - [使用 macOS Keychain](#使用 macOS Keychain)
- 故障排除
- - 常见安装问题
  - [Alpine Linux 特殊要求](#Alpine Linux 特殊要求)
- 更新和维护
- - [更新 Claude Code](#更新 Claude Code)
  - 检查更新状态
- 与开发工具集成
- - [Git Hooks 集成](#Git Hooks 集成)
  - [VS Code 集成](#VS Code 集成)
  - [Shell 别名和函数](#Shell 别名和函数)
- 性能优化
- - 项目上下文管理
  - 命令优化
- 结论

概述

Claude Code 是 Anthropic 开发的智能编程助手工具，可以在终端中运行，理解您的代码库，通过自然语言命令帮助您更快地编程。它能够执行常规任务、解释复杂代码、处理 Git 工作流等。

前置要求

在开始安装之前，请确保您的系统满足以下要求：

macOS 10.15 (Catalina) 或更高版本
有效的 Anthropic API 密钥
管理员权限（用于某些安装方法）

安装方法

方法一：官方安装脚本（推荐）

这是 Anthropic 官方推荐的安装方式：

bash 复制代码

# 安装稳定版本（默认）
curl -fsSL https://claude.ai/install.sh | bash

如果需要安装最新版本：

bash 复制代码

# 安装最新版本
curl -fsSL https://claude.ai/install.sh | bash -s -- --latest

方法二：使用 npm 安装

如果您已经安装了 Node.js v18 或更高版本：

检查 Node.js 版本：

bash 复制代码

node --version

安装 Node.js（如果版本不够）：

bash 复制代码

brew install node

全局安装 Claude Code：

bash 复制代码

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

如果使用 npm 安装后遇到 "command not found" 错误，这通常是 PATH 配置问题：

检查 npm 全局安装路径：

bash 复制代码

npm config get prefix

添加到 PATH（将路径替换为实际路径）：

bash 复制代码

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

方法二：使用 Homebrew（推荐）

Homebrew 是 macOS 最流行的包管理器，提供最简便的安装体验。

安装 Homebrew（如果尚未安装）：

bash 复制代码

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

更新 Homebrew：

bash 复制代码

brew update

安装 Claude CLI：

bash 复制代码

brew install anthropic/claude/claude

验证安装：

bash 复制代码

which claude
claude --version

获取和配置 API 密钥

获取 API 密钥

访问 Anthropic Console
登录您的账户
导航到 API Keys 部分
创建新的 API 密钥并安全保存

配置认证

方法一：环境变量（推荐）

设置环境变量来配置 API 密钥：

bash 复制代码

# 对于 zsh (macOS 默认)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

# 对于 bash
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

方法二：配置文件

创建配置文件：

bash 复制代码

mkdir -p ~/.config/claude
cat << EOF > ~/.config/claude/config.yaml
api_key: "your-api-key-here"
default_model: "claude-3-sonnet-20240229"
max_tokens: 4096
EOF

方法三：交互式配置

运行初始化命令：

bash 复制代码

claude init

验证安装

运行诊断命令检查安装状态：

bash 复制代码

# 检查安装和配置
claude doctor

# 查看版本信息
claude --version

# 测试基本功能
claude "Hello, please help me understand this codebase"

基础使用

简单对话

bash 复制代码

claude "请解释什么是机器学习"

bash 复制代码

  Enter to confirm · Esc to exit
╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                         │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /Users/xxxx                            │
│                                                   │
│   ─────────────────────────────────────────────── │
│                                                   │
│   Overrides (via env):                            │
│                                                   │
│   • API Key: sk-ant-...402e6fd9c15771ed04c49040e9ba │
│   • API Base URL: https://relay.nf.video          │
╰───────────────────────────────────────────────────╯

 Tips for getting started:

  Run /init to create a CLAUDE.md file with instructions for Claude
  Use Claude to help with file analysis, editing, bash commands and git
  Be as specific as you would with another engineer for the best results
  ✔ Run /terminal-setup to set up terminal integration

 Note: You have launched claude in your home directory. For the best
 experience, launch it in a project directory instead.

> Hello,谈谈你 对于Agentic的理解

⏺ Agentic AI是指具有自主决策和行动能力的人工智能系统，主要特征包括：

  核心特点：
  - 自主性 - 能独立制定计划和执行任务，无需人工逐步指导
  - 目标导向 - 围绕明确目标进行推理和决策
  - 工具使用 - 能调用外部工具、API和服务来完成复杂任务
  - 环境感知 - 能理解和适应不同的工作环境和上下文

  与传统AI的区别：
  传统AI更像是"回答机器"，而Agentic AI更像是"行动者" -
  它不仅能理解问题，还能主动采取步骤解决问题。

  实际应用：
  - 代码生成和调试
  - 数据分析和报告生成
  - 自动化工作流程
  - 研究和信息收集

  就像我现在这样 - 我可以使用各种工具(搜索、编辑文件、运行命令等)来自主完成
  复杂的编程任务，而不只是提供建议。

────────────────────────────────────────────────────────────────────────────────
> 你可以为我做什么？你有什么特长？

⏺ 我是Claude Code，专门为软件工程任务设计的AI助手。我的主要能力包括：

  代码开发：
  - 编写、修改、重构代码（支持各种编程语言）
  - 调试和修复bug
  - 代码审查和优化
  - 实现新功能

  项目管理：
  - 搜索和分析代码库
  - 文件操作（读取、编辑、创建）
  - 运行终端命令
  - Git操作（提交、分支管理等）

  工具集成：
  - 运行测试和构建命令
  - 包管理（npm、pip等）
  - 代码格式化和类型检查
  - 与各种开发工具交互

  研究能力：
  - 网络搜索获取最新信息
  - 分析技术文档
  - 理解项目架构和依赖关系

  特长：
  - 自主执行 - 我能独立完成多步骤任务，不需要你逐步指导
  - 并行处理 - 可以同时运行多个工具来提高效率
  - 上下文理解 - 深入理解你的代码库和项目结构
  - 实时反馈 - 边做边验证，确保代码质量

  你有什么具体的编程任务需要帮助吗？

───────────────────────────────────

文件处理

bash 复制代码

# 分析文件内容
claude --file document.txt "请总结这个文档的要点"

# 代码审查
claude --file script.py "请审查这段代码并提出改进建议"

管道操作

bash 复制代码

# 与其他命令结合使用
cat log.txt | claude "分析这些日志文件中的错误模式"

# 处理命令输出
ls -la | claude "解释这个目录结构"

启动 Claude Code

在任何项目目录中启动：

bash 复制代码

cd your-project-directory
claude

常用命令示例

bash 复制代码

# 代码审查
claude "Please review the code in this file for potential improvements"

# 解释复杂代码
claude "Explain how this algorithm works"

# Git 工作流帮助
claude "Help me create a commit message for these changes"

# 重构建议
claude "Suggest refactoring options for this function"

# 添加文档
claude "Add comprehensive documentation to this code"

处理图片和截图

Claude Code 支持图片输入，这对于解释界面或图表特别有用：

快速截图到剪贴板 ：使用 cmd+ctrl+shift+4 截图
粘贴到 Claude ：使用 ctrl+v（注意不是通常的 cmd+v）
拖放图片：直接拖放图片文件到终端

高级配置

创建别名和函数

在 shell 配置文件中添加有用的别名：

bash 复制代码

# 代码审查别名
alias code-review='claude --file'

# 快速问答函数
ask() {
    claude "$*"
}

# 文档生成函数
generate-docs() {
    claude --file "$1" "为这个代码文件生成详细的文档"
}

配置不同的模型

创建针对不同任务的配置：

bash 复制代码

# ~/.config/claude/profiles/coding.yaml
model: "claude-3-opus-20240229"
max_tokens: 8192
temperature: 0.1

# ~/.config/claude/profiles/creative.yaml
model: "claude-3-sonnet-20240229"
max_tokens: 4096
temperature: 0.7

使用特定配置：

bash 复制代码

claude --profile coding "帮我重构这段代码"
claude --profile creative "写一首关于人工智能的诗"

最佳实践

提供具体指令

Claude Code 在收到更具体的指令时成功率会显著提高，特别是在首次尝试时。预先给出清晰的指示可以减少后续的调整需求。

bash 复制代码

# 不推荐：模糊指令
claude "Fix this code"

# 推荐：具体指令
claude "Fix the memory leak in the getData function by properly closing database connections"

利用上下文

Claude Code 理解您的代码库结构，充分利用这一点：

bash 复制代码

# 引用特定文件
claude "In utils/database.js, optimize the connection pooling logic"

# 涉及多个文件的任务
claude "Update the authentication flow across login.js and auth-middleware.js to use JWT tokens"

有效的 Git 工作流

bash 复制代码

# 分析更改
claude "Review my staged changes and suggest improvements before commit"

# 生成提交信息
claude "Generate a commit message for these database schema changes"

# 处理合并冲突
claude "Help resolve this merge conflict in the user authentication module"

安全最佳实践

API 密钥安全

永远不要在代码中硬编码 API 密钥
使用环境变量存储密钥
定期轮换 API 密钥
限制 API 密钥的权限范围

使用 macOS Keychain

更安全的密钥管理方式：

bash 复制代码

# 存储到 keychain
security add-generic-password -a "$USER" -s "anthropic-api-key" -w "your-api-key"

# 在 shell 配置中读取
export ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "anthropic-api-key" -w 2>/dev/null)

故障排除

常见安装问题

问题：权限错误

bash 复制代码

# 不要使用 sudo npm install -g
# 而是配置 npm 不使用 sudo
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

问题：命令未找到

bash 复制代码

# 运行诊断
claude doctor

# 检查安装类型和版本
which claude
claude --version

问题：API 认证失败

bash 复制代码

# 验证 API 密钥设置
echo $ANTHROPIC_API_KEY

# 测试 API 连接
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" https://api.anthropic.com/v1/messages

Alpine Linux 特殊要求

如果在 Alpine Linux 环境中使用：

bash 复制代码

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

更新和维护

更新 Claude Code

Claude Code 默认会自动更新。如果需要手动更新：

bash 复制代码

# 使用官方脚本安装的更新方法
curl -fsSL https://claude.ai/install.sh | bash

# 使用 npm 安装的更新方法
npm update -g @anthropic-ai/claude-code

检查更新状态

bash 复制代码

claude doctor

与开发工具集成

Git Hooks 集成

创建预提交钩子：

bash 复制代码

#!/bin/bash
# .git/hooks/pre-commit
echo "Running Claude Code review..."
claude "Review staged changes for potential issues"

VS Code 集成

虽然 Claude Code 主要在终端中运行，您也可以通过 VS Code 的终端面板使用它：

在 VS Code 中打开集成终端（``Ctrl+```）
直接在终端中运行 Claude Code 命令

Shell 别名和函数

在 shell 配置文件中添加有用的快捷方式：

bash 复制代码

# 代码审查别名
alias review='claude "Review this code for improvements and potential bugs"'

# 快速解释函数
explain() {
    claude "Explain what this code does: $1"
}

# 重构建议函数
refactor() {
    claude "Suggest refactoring improvements for: $1"
}

性能优化

项目上下文管理

Claude Code 会分析您的项目结构。对于大型项目：

确保项目结构清晰
使用有意义的文件和目录命名
保持代码库整洁，移除无用文件

命令优化

bash 复制代码

# 使用具体的文件路径
claude "Review src/components/UserForm.js for accessibility issues"

# 而不是模糊的请求
claude "Check accessibility"

结论

Claude Code 是一个强大的开发工具，能够显著提高编程效率。通过正确安装和配置，结合最佳实践使用，它将成为您开发工作流中的重要助手。

记住定期检查 Claude Code 官方文档获取最新功能和更新。随着工具的不断发展，新功能会定期发布，确保您能充分利用这个强大的 AI 编程助手。

注：本指南基于 2024 年 9 月的信息编写。请参考官方文档获取最新的安装说明和功能更新。