Claude Code 安装、配置与使用完整指南（2026）

Claude Code 是 Anthropic 推出的 AI 驱动代码助手，以终端 CLI 为核心，能够读取整个代码库、编辑文件、运行命令并集成开发工具。它支持 Terminal、VS Code、JetBrains、Desktop App、Web 五种运行环境，需要 Claude Pro 及以上订阅。本文覆盖从安装到高级配置的完整工作流，基于 Claude Code 官方文档（2026 年 3 月）。

Claude Code 是什么？

Claude Code 是一款 Agentic 编码工具，运行在终端中，理解你的代码库并通过自然语言指令完成编码任务。与传统 AI 补全工具不同，Claude Code 能够主动跨多个文件规划、编写和验证代码，处理从写测试、修复 bug 到提交 PR 的完整开发循环。

核心能力一览：

读取和修改整个代码库（跨文件感知）
执行终端命令、管理 git 工作流
通过 MCP 连接外部工具（Jira、Slack、Google Drive 等）
支持多 Agent 并发协作
在 Terminal、VS Code、JetBrains、Desktop、Web、移动端跨端无缝切换

GitHub 数据（2026 年 3 月）： 77k stars，6.3k forks，51 位贡献者，5k+ Issues 持续活跃迭代。

系统要求

在安装前确认你的环境满足以下要求：

项目	要求
macOS	13.0（Ventura）及以上
Windows	Windows 10 1809+ 或 Windows Server 2019+
Linux	Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
内存	4 GB+ RAM
网络	需要互联网连接
Shell	Bash、Zsh、PowerShell 或 CMD
Windows 额外依赖	Git for Windows（必须）

安装方法

Claude Code 提供四种安装方式，推荐使用 Native Install（自动后台更新，无需手动维护版本）。

方法一：Native Install（推荐）

macOS / Linux / WSL：

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

Windows PowerShell：

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

Windows CMD：

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

Native Install 优势：自动后台更新、无依赖、安装最快。

方法二：Homebrew（macOS/Linux）

brew install --cask claude-code

注意：Homebrew 版本不自动更新，需手动执行 brew upgrade claude-code。

方法三：WinGet（Windows）

winget install Anthropic.ClaudeCode

注意：WinGet 版本不自动更新，需手动执行 winget upgrade Anthropic.ClaudeCode。

方法四：npm（已废弃）

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

官方已废弃 npm 安装方式，推荐迁移到 Native Install。若已用 npm 安装，执行以下命令迁移：
curl -fsSL https://claude.ai/install.sh | bash
npm uninstall -g @anthropic-ai/claude-code

安装后验证

# 验证安装成功
claude --version

# 全面检查安装和配置状态
claude doctor

首次登录与认证

安装完成后，进入项目目录并启动：

cd your-project
claude

首次启动会自动打开浏览器完成登录。若浏览器未自动打开，按 c 复制登录链接。

支持的账户类型

账户类型	是否支持 Claude Code	说明
Claude 免费版	❌ 不支持	免费计划不包含 Claude Code
Claude Pro	✅ 支持	个人订阅，推荐个人开发者
Claude Max	✅ 支持	更高用量上限
Claude Teams	✅ 支持	团队协作，集中计费
Claude Enterprise	✅ 支持	SSO、合规、组织级管理
Anthropic Console	✅ 支持	API Key 计费模式
Amazon Bedrock	✅ 支持	设置环境变量，无需浏览器登录
Google Vertex AI	✅ 支持	设置环境变量，无需浏览器登录

退出登录：在 Claude Code 交互界面输入 /logout。

通过第三方 API 接入 Claude Code

国内开发者在无法直接访问 Anthropic API 的环境下，可通过兼容 Anthropic 标准接口的第三方推理服务接入。例如，七牛云 AI 推理服务兼容 Anthropic API 格式，通过设置 ANTHROPIC_BASE_URL 环境变量即可将 Claude Code 路由至该服务，无需修改其他配置：

export ANTHROPIC_BASE_URL="https://api.qnaigc.com/v1"
export ANTHROPIC_API_KEY="your-key"
claude

具体配置说明可参考：通过 Router 配置 Claude Code

核心配置体系

Claude Code 使用四层范围配置系统，优先级从高到低：

Managed（组织强制，不可覆盖）
    ↓
Local（本地个人，不提交 git）
    ↓
Project（团队共享，提交 git）
    ↓
User（全局个人）

配置文件位置

范围	文件路径	用途
User	`~/.claude/settings.json`	全局个人设置
Project	`.claude/settings.json`	团队共享（提交 git）
Local	`.claude/settings.local.json`	个人本地覆盖（不提交 git）
Managed	`/Library/Application Support/ClaudeCode/managed-settings.json`（macOS）	组织强制策略

settings.json 完整配置说明

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",

  // 权限控制：allow > ask > deny 三档
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  },

  // 模型选择
  "model": "claude-sonnet-4-6",

  // 自动更新渠道：latest（即时）或 stable（延迟约一周）
  "autoUpdatesChannel": "stable",

  // 环境变量注入
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "NODE_ENV": "development"
  },

  // 沙箱隔离（macOS / Linux / WSL2 支持）
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["//tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

权限规则匹配顺序： deny 先于 ask，ask 先于 allow，先匹配先生效。

CLAUDE.md：给 AI 的持久化指令

CLAUDE.md 是项目根目录下的 Markdown 文件，Claude Code 每次会话开始时自动读取，用于设定代码规范、架构决策和团队约定。

文件位置：

~/.claude/CLAUDE.md：全局个人指令（所有项目生效）
CLAUDE.md 或 .claude/CLAUDE.md：项目级指令（团队共享）

典型 CLAUDE.md 示例：

# 项目规范

## 技术约定
- 使用 TypeScript 严格模式，禁止 `any` 类型
- 所有新功能必须包含单元测试（覆盖率 ≥ 80%）
- 遵循 ESLint 配置，提交前运行 `npm run lint`

## Git 约定
- 使用 Conventional Commits 格式（feat/fix/docs/refactor）
- PR 需要至少两名代码审查者批准

## 架构说明
- 状态管理使用 Zustand，禁止直接修改 Redux store
- API 调用统一通过 `src/api/` 目录的封装函数

Claude Code 还会自动构建记忆（Auto Memory），在会话中学习构建命令、调试发现等信息，跨会话持久保存，无需手动维护。

MCP 集成：连接外部工具

MCP（Model Context Protocol）是开放标准，让 Claude Code 通过工具读取 Google Drive、更新 Jira、拉取 Slack 消息等。Claude Code 支持在 ~/.claude.json（用户级）和 .mcp.json（项目级）两处配置 MCP 服务。

用户级 MCP 配置（~/.claude.json）：

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp.js"],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

项目级 MCP 配置（.mcp.json，随 git 提交给团队）：

{
  "github": {
    "command": "node",
    "args": ["./tools/github-mcp.js"]
  }
}

对于希望在不本地部署 MCP Server 的场景，也可以通过标准化 MCP 托管服务接入，直接构建 Agent 应用，无需管理服务器生命周期。

常用 CLI 命令速查

# 启动交互式会话
claude

# 非交互式执行单条指令
claude -p "为 auth 模块写测试并修复失败项"

# 管道输入
tail -f app.log | claude -p "发现异常时通知我"
git diff main --name-only | claude -p "检查这些变更的安全问题"

# 版本管理
claude --version          # 查看当前版本
claude update             # 立即应用最新更新
claude doctor             # 诊断安装和配置问题

# 会话内斜杠命令
/status                   # 查看活跃配置和来源
/logout                   # 退出登录
/config                   # 打开配置界面
/bug                      # 报告 bug

VS Code 和 JetBrains 集成

VS Code / Cursor 安装

打开扩展视图（Cmd+Shift+X / Ctrl+Shift+X）
搜索 "Claude Code"
安装后打开命令面板（Cmd+Shift+P），输入 "Claude Code"，选择 Open in New Tab

或直接在 VS Code 中点击：vscode:extension/anthropic.claude-code

JetBrains 安装

从 JetBrains Marketplace 安装 Claude Code 插件（插件 ID：27310），重启 IDE 生效。

IDE 集成优势：

内联 diff 预览（直接在编辑器中查看 AI 建议的改动）
@-mentions 引用文件/符号
对话历史保留
Plan Review（在执行前预览 AI 的操作计划）

卸载 Claude Code

Native Install（macOS/Linux/WSL）

# 删除二进制文件和版本文件
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew / WinGet / npm

brew uninstall --cask claude-code       # Homebrew
winget uninstall Anthropic.ClaudeCode   # WinGet
npm uninstall -g @anthropic-ai/claude-code  # npm

删除配置文件（可选，不可逆）

# macOS/Linux：删除所有设置、MCP 配置、会话历史
rm -rf ~/.claude
rm ~/.claude.json

# 删除项目级配置（在项目目录中执行）
rm -rf .claude
rm -f .mcp.json

FAQ

Q1：Claude Code 和 claude.ai 聊天有什么区别？
claude.ai 是基于浏览器的对话界面，适合问答和内容生成。Claude Code 是专为开发场景设计的 Agentic 工具，能读取本地文件系统、执行终端命令、管理 git，并跨多个文件主动完成编码任务。两者账户体系相同，Claude Pro/Max 订阅两个产品均可使用。

Q2：Claude Code 免费版能用吗？
不能。Claude 免费计划不包含 Claude Code 访问权限。需要订阅 Claude Pro（$20/月）及以上计划，或通过 Anthropic Console 使用 API Key 计费模式。

Q3：如何在团队中统一 Claude Code 配置？
将配置写入项目根目录的 .claude/settings.json 和 CLAUDE.md 并提交到 git。团队成员 clone 仓库后自动继承配置。企业级场景可使用 managed-settings.json 强制下发无法覆盖的策略。

Q4：Claude Code 会把我的代码上传到 Anthropic 吗？
Claude Code 不会将反馈用于模型训练，且对用户会话数据实施访问限制和保留期限制。敏感代码场景可通过 Amazon Bedrock 或 Google Vertex AI 接入，在云提供商基础设施内处理，不经过 Anthropic 服务器。

Q5：在 Alpine Linux 上安装失败怎么解决？
Alpine 等 musl 系发行版需要额外安装依赖，并禁用内置 ripgrep：

apk add libgcc libstdc++ ripgrep
# 在 settings.json 中设置：
# { "env": { "USE_BUILTIN_RIPGREP": "0" } }

小结

Claude Code 是 Anthropic 官方推出的 Agentic 编码工具，核心安装命令为 curl -fsSL https://claude.ai/install.sh | bash，需要 Claude Pro 及以上订阅。配置体系通过 settings.json（权限控制）、CLAUDE.md（持久化指令）、.mcp.json（工具集成）三个核心文件分层管理，支持个人、团队、企业三种场景。本文数据来源于 Claude Code 官方文档（code.claude.com）和 GitHub 仓库（2026 年 3 月），适用于当前最新版本。

延伸资源

posted @ 2026-03-13 09:04 七牛云行业应用阅读(431) 评论(0) 收藏举报

刷新页面返回顶部

qiniushanghai