乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > Claude Code 安装与配置完全指南

Claude Code 安装与配置完全指南

当前时间： 2026-08-17 17:11:26 分类：办公文件 评论(0)
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 域名可能受限，需要实测确认。

三、安装方式对比表

安装方式
自动更新
需 Node.js
难度
国内可行性
适用场景
原生安装器
✅ 支持
否
⭐
❌ 不可行
海外用户首选
npm
❌ 不支持
是
⭐
✅ 可行
国内用户首选
Homebrew
❌ 不支持
否
⭐
⚠️ 部分
macOS 用户
WinGet
❌ 不支持
否
⭐
⚠️ 部分
Windows 用户
apt/dnf/apk
❌ 不支持
否
⭐⭐
⚠️ 不确定
Linux 服务器

四、认证与登录

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

优先级
认证方式
说明
国内可行性
1
云服务提供商
Bedrock / Vertex / Foundry
✅ 可行
2
ANTHROPIC_AUTH_TOKEN
Bearer Token，用于 LLM 网关
✅ 可行（配合中转）
3
ANTHROPIC_API_KEY
Anthropic 官方 API Key
✅ 可行（配合代理/中转）
4
apiKeyHelper 脚本
动态获取凭证（如 Vault）
✅ 可行
5
OAuth 登录（/login）
浏览器登录 Claude.ai
❌ 不可行（需访问 claude.ai）

💡 国内用户推荐： 使用 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 需要放行的域名

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

域名
用途
api.anthropic.com
Claude API 请求
claude.ai
OAuth 认证
platform.claude.com
Console 账号认证
downloads.claude.ai
插件下载、原生安装/更新

六、配置文件详解

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

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

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

作用域
文件位置
说明
Managed
macOS: /Library/Application Support/ClaudeCode/managed-settings.jsonLinux: /etc/claude-code/managed-settings.jsonWindows: C:\Program Files\ClaudeCode\managed-settings.json
组织级管理配置，不可被覆盖
User~/.claude/settings.json
个人配置，跨项目生效
Project.claude/settings.json
项目配置，提交到 Git 共享
Local.claude/settings.local.json
个人项目配置，不提交

常用配置项示例：

{"$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 个版本。

常用配置项：

配置项
说明
autoConnectIde
自动连接 IDE
editorMode
输入模式，如 "vim"
hasCompletedOnboarding
是否已完成新手引导（仅跳过引导页，不跳过登录）
showTurnDuration
显示每轮处理时间
terminalProgressBarEnabled
终端进度条

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

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

作用域
文件位置
用途
组织级
macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdLinux: /etc/claude-code/CLAUDE.md
公司统一编码规范、安全策略
项目级./CLAUDE.md
 或 ./.claude/CLAUDE.md
项目架构、编码规范、流程说明
个人级~/.claude/CLAUDE.md
个人偏好，跨项目生效
本地级./CLAUDE.local.md
个人项目配置，不提交到 Git

编写原则：

  • • 控制在 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 等密钥管理服务获取临时凭证。

七、配置文件全景图

文件
位置
用途
settings.json
多个位置（见 6.1）
核心配置：权限、模型、环境变量
~/.claude.json
用户主目录
状态、OAuth、MCP、偏好
CLAUDE.md
多个位置（见 6.3）
项目指令与编码规范
CLAUDE.local.md
项目根目录
个人项目指令（gitignore）
.claude/rules/*.md
项目 .claude/rules/
模块化规则，支持按路径加载
.claude/agents/*.md
项目或用户 .claude/
子代理配置
.mcp.json
项目根目录
MCP 服务器配置
.credentials.json~/.claude/
认证凭证（Linux/Win）
MEMORY.md~/.claude/projects/<project>/memory/
自动记忆索引

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

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

  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