【weelinking系列Claude教程】 04 - Claude Code 安装与配置

04 - Claude Code 安装与配置

从安装到配置，手把手带你搭建 Claude Code 开发环境。
weelinking企业级API中转站

1. Claude Code 是什么？

Claude Code 是 Anthropic 官方的 命令行 AI 编程工具（CLI）。它直接运行在你的终端中，能够：

理解整个代码库的结构和上下文
通过自然语言编辑文件、执行命令
自主完成多步骤任务（Agent 模式）
处理 Git 工作流（提交、PR、代码审查）
通过 MCP 连接外部工具和数据源
集成到 VS Code / JetBrains IDE

它不是一个简单的 AI 聊天窗口，而是一个能直接操作你项目的 AI Agent。

2. 安装

2.1 系统要求

要求	说明
操作系统	macOS 10.15+、Ubuntu 20.04+ / Debian 10+、Windows 10+（通过 WSL）
Node.js	v18+
网络	需要访问 Anthropic API

2.2 安装方式

方式零---前置操作：安装NodeJS 和 git

方式一：npm 安装（跨平台通用）【推荐这个】

bash 复制代码

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

方式二：macOS Homebrew

bash 复制代码

brew install claude-code

方式三：Windows WinGet

bash 复制代码

winget install claude-code

2.3 验证安装

bash 复制代码

claude --version
# 输出示例: claude-code v2.x.x

2.4 更新

bash 复制代码

claude update
# 或
npm update -g @anthropic-ai/claude-code

3. 认证设置

Claude Code 支持两种认证方式：

3.1 3.2 方式一：Claude 订阅（推荐个人使用）

如果你有 Claude Pro（ $20/月）或 Claude Max（$ 100~200/月）订阅：

bash 复制代码

claude
# 首次启动会打开浏览器进行 OAuth 认证
# 登录你的 Claude 账号即可

3.3 方式二：API Key（推荐团队/企业使用）

参照这篇前置文章【weelinking系列Claude教程】 02 - Claude API 开发实战

bash 复制代码

# 环境变量（推荐） 

# Windows PowerShell 永久生效 #每个命令要执行5秒钟，不是卡了
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.weelinking.com", [System.EnvironmentVariableTarget]::User)
#复制你刚刚创建的密钥替换
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk替换成你创建的密钥", [System.EnvironmentVariableTarget]::User)

# Linux / macOS
export ANTHROPIC_BASE_URL = "https://api.weelinking.com"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 启动时会自动使用 API Key
claude

两种方式的对比：

特性	Claude 订阅	API Key	weelinking💯
计费方式	包含在月费中	按 token 计费	包月/按token
使用限制	有配额（Max 最高）	无上限（按量付费）	无上限（按量付费）
适合场景	个人开发者	团队、CI/CD、自动化	个人、团队
设置难度	简单（浏览器登录）需要纯净IP	需要管理 Key	国内直连、不折腾💯

4. 首次启动

4.1 进入项目目录并启动

bash 复制代码

cd /path/to/your/project
claude

4.2 初始化项目（创建 CLAUDE.md）

bash 复制代码

# 在交互式会话中输入：
/init

这会在项目根目录创建 CLAUDE.md，Claude 会自动分析你的项目并生成初始配置。

4.3 首次使用的推荐操作

bash 复制代码

# 1. 启动 Claude Code
claude

# 2. 初始化项目
> /init

# 3. 让 Claude 了解你的项目
> 请概述这个项目的技术栈、目录结构和核心功能

# 4. 试一下简单任务
> 帮我检查 package.json 中有哪些过时的依赖

# 5. 查看健康状态
> /doctor

5. 配置体系

Claude Code 的配置分为三层：

5.1 配置层级

复制代码

全局配置（~/.claude/）
  └─ 项目配置（项目根目录）
       └─ 子目录配置（子目录）

5.2 全局配置目录

复制代码

~/.claude/
├── CLAUDE.md           # 全局指令（适用于所有项目）
├── settings.json       # 全局设置（MCP、Hooks、权限）
├── credentials.json    # 认证信息（自动管理）
└── skills/             # 全局技能

5.3 项目配置

复制代码

your-project/
├── CLAUDE.md           # 项目级指令
├── .claude/
│   └── settings.json   # 项目级设置
├── .mcp.json           # 共享 MCP 服务器配置
└── src/
    └── CLAUDE.md       # 子目录特定指令

5.4 settings.json 结构

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm test)",
      "Read",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": []
  },
  "mcpServers": {}
}

6. 权限管理

Claude Code 的权限系统确保安全性：

6.1 权限类型

权限级别	说明	示例
自动允许	只读操作	读文件、搜索代码
需确认	写操作、Shell 命令	编辑文件、运行脚本
总是拒绝	高风险操作	删除目录、修改系统文件

6.2 配置权限白名单

在 settings.json 中预设允许的操作，减少确认弹窗：

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(python *)",
      "Bash(git *)",
      "Read",
      "Write(*.py)",
      "Write(*.js)",
      "Write(*.ts)"
    ]
  }
}

6.3 实战：为 Python 项目配置权限

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(python *)",
      "Bash(pip install *)",
      "Bash(pytest *)",
      "Bash(git *)",
      "Read",
      "Write(*.py)",
      "Write(*.md)",
      "Write(requirements.txt)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

7. 模型选择

Claude Code 默认使用 Sonnet，但你可以切换：

bash 复制代码

# 在会话中切换模型
> /model

# 命令行指定模型
claude --model claude-opus-4-5-20250514

推荐策略：

日常开发： Sonnet（默认，性价比最高）
复杂架构决策： 临时切换 Opus
简单查询/批量任务： Haiku

8. 网络代理配置

如果你需要通过代理访问：

bash 复制代码

# HTTP 代理
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

# SOCKS 代理
export ALL_PROXY=socks5://proxy:port

9. 常见安装问题

问题 1：npm 安装失败

bash 复制代码

# 清理缓存后重试
npm cache clean --force
npm install -g @anthropic-ai/claude-code

问题 2：权限不足（macOS/Linux）

bash 复制代码

# 方式一：使用 sudo（不推荐）
sudo npm install -g @anthropic-ai/claude-code

# 方式二：修改 npm 全局目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

问题 3：Node.js 版本过低

bash 复制代码

# 检查版本
node --version

# 使用 nvm 升级
nvm install 18
nvm use 18

问题 4：认证失败

bash 复制代码

# 重新认证
claude auth login

# 检查 API Key
echo $ANTHROPIC_API_KEY

# 健康检查
claude /doctor

10. 实战：完整的项目初始化流程

以下是一个 Python Web 项目的完整初始化过程：

bash 复制代码

# 1. 进入项目
cd ~/projects/my-fastapi-app

# 2. 启动 Claude Code
claude

# 3. 初始化
> /init

# Claude 会分析项目结构并生成 CLAUDE.md，内容类似：
# - 技术栈：Python 3.11 + FastAPI + SQLAlchemy
# - 构建命令：pip install -r requirements.txt
# - 测试命令：pytest tests/
# - 项目结构说明...

# 4. 补充自定义配置
> /memory

# 在 CLAUDE.md 中添加：
# - 编码规范（如 PEP 8）
# - 分支策略（如 Git Flow）
# - 部署流程
# - 团队约定

# 5. 验证一切正常
> 请列出项目中所有的 API 端点

# 6. 开始工作！
> 帮我为 /api/users 端点添加分页功能

weelinking企业级API中转站
上一篇： 03-Prompt Engineering 实战指南
下一篇： 05-Claude Code 核心命令与工作流