Claude Code 安装与配置完全指南

Claude Code 安装与配置完全指南

包含安装方式对比、国内可行性分析、配置文件详解

更新日期：2026 年 4 月 23 日，基于 Claude Code v2.1.118

一、概述

Claude Code 是 Anthropic 官方推出的 AI 编程助手，它能够理解整个代码库、编辑文件、运行命令、并与开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。

系统要求： macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+，4GB+ RAM，x64 或 ARM64 处理器，需要网络连接。

账号要求： 需要 Claude Pro、Max、Team、Enterprise 或 Console 账号。免费版 Claude.ai 不支持 Claude Code。也可通过 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 等第三方提供商使用。

二、安装方式详解

2.1 原生安装器（官方推荐）

这是 Anthropic 官方首推的安装方式，通过一行命令从 claude.ai 下载并安装原生二进制文件。

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

优点： 支持后台自动更新，始终保持最新版本；安装的是原生二进制，不依赖 Node.js；官方推荐、文档完善。

缺点： 需要访问 claude.ai 域名下载安装脚本和二进制文件。

⚠️ 国内可行性：不可行。 claude.ai 域名在中国大陆无法直接访问，安装脚本和二进制文件均无法下载。除非终端配置了可访问海外的代理（HTTPS_PROXY）。

2.2 npm 全局安装

通过 Node.js 的包管理器 npm 安装。实际上 npm 包内部也是下载原生二进制文件，并通过 postinstall 脚本链接到位。

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

前提条件： Node.js 18 或更高版本。

优点： 走 npm registry，可使用淘宝镜像等国内源；无需直接访问 claude.ai；安装简单、一行命令。

缺点： 不支持自动更新，需要手动重新安装；依赖 Node.js 环境；官方已不作为首推方案。

✅ 国内可行性：国内最可行的方案。 如果官方 npm 源不稳定，可切换到淘宝镜像：npm config set registry https://registry.npmmirror.com

2.3 Homebrew（macOS）

macOS 用户可通过 Homebrew 安装，提供两个 cask：

# 稳定版（比最新版延迟约一周，跳过有重大回归的版本）brew install --cask claude-code# 最新版（第一时间获取新版本）brew install --cask claude-code@latest

优点： Homebrew 用户熟悉的安装/卸载/管理流程；稳定版 cask 自动跳过问题版本。

缺点： 不支持自动更新，需要 brew upgrade；安装过程需要访问 GitHub。

⚠️ 国内可行性：部分可行。 Homebrew 本身依赖 GitHub，在国内可能较慢或不稳定，但可通过配置 Homebrew 镜像源改善。

2.4 WinGet（Windows）

Windows 用户可通过系统自带的 WinGet 包管理器安装：

winget install Anthropic.ClaudeCode

优点： Windows 原生包管理器，无额外依赖。

缺点： 不支持自动更新；需要访问 GitHub 下载安装包。

⚠️ 国内可行性：部分可行。 WinGet 包的下载源为 GitHub，国内可能下载较慢。

2.5 Linux 包管理器（apt / dnf / apk）

支持 Debian/Ubuntu（apt）、Fedora/RHEL（dnf）、Alpine（apk）的原生包管理器。以 apt 为例：

sudo install -d -m 0755 /etc/apt/keyringssudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \  -o /etc/apt/keyrings/claude-code.ascecho"deb [signed-by=/etc/apt/keyrings/claude-code.asc] \  https://downloads.claude.ai/claude-code/apt/stable stable main" \  | sudotee /etc/apt/sources.list.d/claude-code.listsudo apt update && sudo apt install claude-code

优点： 融入系统包管理流程；支持 GPG 签名验证。

缺点： 不支持自动更新；仓库地址在 downloads.claude.ai。

⚠️ 国内可行性：不确定。 downloads.claude.ai 域名可能受限，需要实测确认。

三、安装方式对比表

四、认证与登录

安装完成后，需要认证才能使用。Claude Code 支持多种认证方式，其优先级从高到低如下：

💡 国内用户推荐： 使用 ANTHROPIC_API_KEY 环境变量可以跳过 OAuth 浏览器登录流程。配合 ANTHROPIC_BASE_URL 指向中转服务，即可在国内网络环境下使用。

4.1 国内用户快速配置示例

在 ~/.zshrc 或 ~/.bashrc 中添加以下环境变量：

方案一：官方 API Key + 代理

export ANTHROPIC_API_KEY=sk-ant-your-key-hereexport HTTPS_PROXY=http://127.0.0.1:7890export HTTP_PROXY=http://127.0.0.1:7890

方案二：第三方中转服务（无需代理）

export ANTHROPIC_API_KEY=your-relay-keyexport ANTHROPIC_BASE_URL=https://your-relay-service.com

配置完成后执行 source ~/.zshrc 并运行 claude 即可。

五、网络与代理配置

Claude Code 支持标准的代理环境变量、自定义 CA 证书和 mTLS 认证。

5.1 代理环境变量

# HTTPS 代理（推荐）export HTTPS_PROXY=https://proxy.example.com:8080# HTTP 代理export HTTP_PROXY=http://proxy.example.com:8080# 跳过代理的地址export NO_PROXY="localhost 192.168.1.1 example.com"

⚠️ 注意： Claude Code 不支持 SOCKS 代理。如果你的代理工具只提供 SOCKS5，需要用 privoxy 等工具转换为 HTTP 代理。

5.2 自定义 CA 证书

企业环境中如果使用自签名证书或 TLS 检查代理：

# 自定义 CA 证书export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem# 证书库配置（默认同时信任捆绑 CA 和系统 CA）export CLAUDE_CODE_CERT_STORE=bundled,system

5.3 mTLS 双向认证

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pemexport CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pemexport CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

5.4 需要放行的域名

如果你在受限网络环境中，需要在防火墙/代理中放行以下域名：

六、配置文件详解

Claude Code 的配置体系分为多个层级，优先级从高到低为：Managed → 命令行参数 → Local → Project → User。数组类型的配置会跨层级合并（拼接并去重）。

6.1 settings.json —— 核心配置文件

这是 Claude Code 最重要的配置文件，存在于多个位置：

常用配置项示例：

{"$schema":"https://json.schemastore.org/claude-code-settings.json","permissions":{"allow":["Bash(npm run lint)","Bash(npm run test *)"],"deny":["Bash(curl *)","Read(./.env)"],"defaultMode":"acceptEdits"},"model":"claude-sonnet-4-6","env":{"ANTHROPIC_API_KEY":"sk-ant-xxx","HTTPS_PROXY":"http://127.0.0.1:7890"},"autoUpdatesChannel":"stable","language":"chinese","alwaysThinkingEnabled":true}

主要配置类别包括：

• • permissions — 工具权限控制，allow/deny/defaultMode
• • model — 模型选择，如 claude-sonnet-4-6
• • env — 环境变量，每次会话自动注入
• • sandbox — 沙箱隔离，控制文件系统和网络访问
• • hooks — 钩子，在 Claude Code 操作前后运行自定义命令
• • attribution — 提交签名，自定义 commit/PR 的署名信息
• • autoUpdatesChannel — 更新通道，"latest" 或 "stable"

6.2 ~/.claude.json —— 全局状态文件

存储用户偏好、OAuth 会话、MCP 配置、项目状态和缓存。自动备份最近 5 个版本。

常用配置项：

6.3 CLAUDE.md —— 项目指令文件

CLAUDE.md 是 Claude Code 的"记忆系统"核心，用 Markdown 格式编写，每次会话开始时自动加载到上下文窗口。

编写原则：

• • 控制在 200 行以内，过长会消耗上下文并降低遵从度
• • 使用 Markdown 标题和列表组织内容
• • 指令要具体可验证（如"使用 2 空格缩进"而非"格式化代码"）
• • 支持 @path/to/file 语法导入其他文件
• • 可通过 /init 命令自动生成初始版本

6.4 .claude/rules/ —— 模块化规则

对于大型项目，可将规则拆分到 .claude/rules/ 目录下的独立 Markdown 文件中。支持通过 YAML frontmatter 的 paths 字段按文件路径条件加载：

---paths:  - "src/api/**/*.ts"---# API 开发规范- 所有 API 端点必须包含输入验证- 使用统一的错误响应格式

没有 paths 字段的规则会在每次会话启动时无条件加载。

6.5 .mcp.json —— MCP 服务器配置

项目级的 MCP（Model Context Protocol）服务器配置文件，放在项目根目录。用户级的 MCP 配置则存储在 ~/.claude.json 中。通过 MCP，Claude Code 可以连接 Google Drive、Jira、Slack 等外部数据源。

6.6 自动记忆（Auto Memory）

Claude Code 会自动学习和记忆你的工作习惯，存储在 ~/.claude/projects/<project>/memory/ 目录下。其中 MEMORY.md 是索引文件，每次会话开始时加载前 200 行或 25KB。

管理方式：

• • 通过 /memory 命令查看和编辑
• • 在 settings.json 中设置 "autoMemoryEnabled": false 关闭
• • 所有记忆文件都是纯 Markdown，可以随时手动编辑或删除

6.7 凭证存储

认证凭证的存储位置因平台而异：

• • macOS — 存储在加密的 Keychain 中
• • Linux / Windows — 存储在 ~/.claude/.credentials.json（Linux 下权限为 0600）

可通过 apiKeyHelper 配置动态凭证脚本，从 Vault 等密钥管理服务获取临时凭证。

七、配置文件全景图

八、国内用户快速上手总结

结合以上内容，国内用户的推荐流程如下：

1. 1. 安装 Node.js 18+（如果还没有），推荐使用 nvm 管理版本
2. 2. 通过 npm 安装 Claude Code：npm install -g @anthropic-ai/claude-code，如需可先切换淘宝镜像
3. 3. 配置认证： 设置 ANTHROPIC_API_KEY 环境变量跳过 OAuth 登录
4. 4. 配置网络： 设置 HTTPS_PROXY 或 ANTHROPIC_BASE_URL 解决网络访问问题
5. 5. 运行 claude 命令即可开始使用

更多信息请参考官方文档：https://code.claude.com/docs