Claude Code 安装、配置、依赖与使用说明书

📢个人主页：编程的一拳超人

⛺️ 欢迎关注：👍点赞 👂🏽留言 😍收藏 💞 💞 💞

于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。

Claude Code 安装、配置、依赖与使用说明书

版本基准：2026-07-22 Anthropic 官方文档
重要提示：Claude Code 更新频繁，部署前务必执行claude doctor并复核官方页面

一、产品形态与选型

Claude Code 是 Anthropic 面向软件开发的智能编码 Agent，具备代码读写、文件搜索、测试执行、Git 操作能力，并可通过 MCP 协议接入外部工具。

选型建议：日常开发可选 CLI 或 IDE 扩展；并行任务与 Diff 审查用 Desktop；无人值守自动化用claude -p或 GitHub Actions；企业统一认证走 Console / Bedrock / Google Cloud / Microsoft Foundry。

二、安装前准备

2.1 依赖项全景判断

核心结论：使用官方原生安装器时，无需预先安装 Node.js；Git 不是启动硬性依赖，但开发项目建议安装。不要盲目预装所有语言环境，按需安装即可。

2.2 Git 的作用与安装验证

Git是源代码版本管理工具。Claude Code 在无 Git 的目录中也能读写文件，但 Git 能提供：变更审查、分支隔离、误改回滚、Diff 分析等关键能力。

Ubuntu / Debian 安装命令：

sudoaptupdate# 更新软件源索引sudoaptinstallgit# 安装 Gitgit--version# 验证安装版本gitconfig--globaluser.name"Your Name"# 设置全局提交用户名gitconfig--globaluser.email"you@example.com"# 设置全局提交邮箱

技术标注：sudo= 以管理员权限执行；--global= 当前用户全局生效；仅为单项目配置时去掉该参数。

2.3 Node.js 依赖边界澄清

原生安装器不依赖 Node.js。仅以下三种情况需要 Node.js / npm：

1. 选择 npm 全局安装方式
2. 目标项目本身是 Node.js 项目
3. 项目构建/测试/格式化命令依赖 npm

安装前环境检查：

node--version# 查看 Node.js 版本npm--version# 查看 npm 版本npmconfig get prefix# 查看 npm 全局安装目录（排查 PATH 问题用）

安全提示：不要使用sudo npm install -g，会造成系统目录权限混乱。

2.4 项目运行时 ≠ Claude Code 依赖

Python、Java、Go、Rust、Docker 等不是Claude Code 的统一前置依赖，仅在执行对应项目命令时才需要。

2.5 系统要求与平台差异

官方支持矩阵：

• 系统版本：macOS 13+、Windows 10 1809+ / Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+
• 硬件要求：至少 4 GB RAM，支持 x64 / ARM64 架构
• 网络要求：需可访问 Anthropic 服务

Windows 双路线说明：

1. 原生 Windows：PowerShell / CMD 安装，适配 Windows 原生工具链
2. WSL 1 / 2：WSL 终端内安装，适配 Linux 工具链 —— 注意不要混用 Windows 路径与 WSL 路径

账号权限说明：Pro / Max、Teams / Enterprise、Console 账号可用；免费 Claude.ai 账号不含 Claude Code 权限。不要将 API Key 提交到 Git、写入 CLAUDE.md 或聊天记录中。

三、安装方式

3.1 原生安装器（推荐）

macOS / Linux / WSL：

curl-fsSLhttps://claude.ai/install.sh|bash

参数拆解：-f遇 HTTP 错误直接失败；-s静默模式；-S静默时仍显示错误；-L跟随重定向

Windows PowerShell：

irmhttps://claude.ai/install.ps1|iex

参数拆解：irm= Invoke-RestMethod 别名；iex= Invoke-Expression 别名；无需管理员权限

Windows CMD：

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

注意：&&是 CMD 语法；在 PowerShell 中执行会报错，应改用 PowerShell 对应命令

指定 stable 频道安装：

# macOS / Linuxcurl-fsSLhttps://claude.ai/install.sh|bash-sstable# PowerShell&([scriptblock]::Create((irm https://claude.ai/install.ps1)))stable

安装指定版本：

curl-fsSLhttps://claude.ai/install.sh|bash-s2.1.89

版本固定适合企业环境验证；不建议长期使用过旧版本。原生安装器默认后台自动更新。

3.2 Homebrew（macOS）

brewinstall--caskclaude-code# 安装brew upgrade claude-code# 升级brew uninstall--caskclaude-code# 卸载

claude-code跟随 stable 频道；claude-code@latest跟随 latest 频道。Homebrew 版本不由 Claude Code 自动升级，更新可能略滞后。

3.3 WinGet（Windows）

winget install Anthropic.ClaudeCode# 安装winget upgrade Anthropic.ClaudeCode# 升级winget uninstall Anthropic.ClaudeCode# 卸载

3.4 Debian / Ubuntu（apt 仓库）

# 1. 创建密钥目录sudoinstall-d-m0755 /etc/apt/keyrings# 2. 导入签名密钥sudocurl-fsSLhttps://downloads.claude.ai/keys/claude-code.asc\-o/etc/apt/keyrings/claude-code.asc# 3. 添加软件源echo"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.list# 4. 刷新索引并安装sudoaptupdatesudoaptinstallclaude-code

升级与卸载：

sudoaptupdate&&sudoaptupgrade claude-code# 升级sudoaptremove claude-code# 卸载

3.5 Fedora / RHEL（dnf 仓库）

# 添加 yum 仓库配置sudotee/etc/yum.repos.d/claude-code.repo<<'EOF' [claude-code] name=Claude Code baseurl=https://downloads.claude.ai/claude-code/rpm/stable enabled=1 gpgcheck=1 gpgkey=https://downloads.claude.ai/keys/claude-code.asc EOFsudodnfinstallclaude-code# 安装sudodnf upgrade claude-code# 升级sudodnf remove claude-code# 卸载

3.6 Alpine Linux（apk）

# 导入公钥wget-O/etc/apk/keys/claude-code.rsa.pub https://downloads.claude.ai/keys/claude-code.rsa.pub# 添加仓库源echo"https://downloads.claude.ai/claude-code/apk/stable">>/etc/apk/repositories# 安装与升级apkaddclaude-code apk update&&apk upgrade claude-code

Alpine 额外依赖：bash、curl、libgcc、libstdc++、ripgrep。musl 环境搜索异常时，在 settings 中配置：

{"env":{"USE_BUILTIN_RIPGREP":"0"}}

3.7 npm 全局安装

npminstall-g@anthropic-ai/claude-code# 安装稳定版npminstall-g@anthropic-ai/claude-code@latest# 安装最新版

版本要求：自 2.1.198 起要求 Node.js 22+，且包管理器需支持 optional dependencies。

适用场景：已有 Node.js 版本管理体系的团队；新部署优先选择原生安装器。

3.8 Desktop、IDE 与远程形态

• Desktop：适合不熟悉终端、需要多会话并行、可视化 Diff / 预览的用户
• VS Code 扩展：要求 VS Code 1.94+，扩展面板自带 CLI；若在集成终端执行claude仍需单独安装 CLI
• JetBrains 集成：适配 IntelliJ IDEA、PyCharm、WebStorm 等
• Web / Remote Control：适合云端与跨设备续作，需确保仓库、分支、凭据连接正确

四、验证与登录

claude--version# 打印版本号claude doctor# 只读模式：安装与配置完整性诊断claude# 启动交互式会话

首次登录流程：自动打开浏览器完成 OAuth 授权。WSL / SSH / 容器环境无法访问本机回调时，按c复制登录 URL，在浏览器完成登录后将 code 粘贴回终端。

API Key 非交互模式：

# macOS / LinuxexportANTHROPIC_API_KEY="你的密钥"claude-p"解释这个项目的构建流程"# PowerShell$env:ANTHROPIC_API_KEY="你的密钥"claude-p"解释这个项目的构建流程"

安全红线：密钥不要提交到代码仓库、写入共享脚本或配置文件。

五、交互式使用

启动会话：

cdpath/to/project# 进入项目目录（决定工作边界）claude# 空白会话启动claude"先分析项目结构，再告诉我实现登录功能需要修改哪些文件"# 带初始任务启动

恢复会话：

claude--continue# 或 -c：继续当前目录最近一次会话claude--resumeSESSION_ID# 或 -r：按 ID 恢复指定会话claude-rSESSION_ID"继续完成剩余工作"# 恢复并立即追加任务

常用斜杠命令速查表：

最佳实践：先调查与规划 → 再允许修改 → 修改后运行测试 → 最后检查git diff与git status。

六、CLI 参数详解

6.1 非交互与输出控制

claude-p"运行测试并解释失败原因"# 非交互模式：执行后直接退出claude-p"检查变更"--output-format json# 单次 JSON 输出claude-p--max-turns3"只分析，不修改代码"# 限制工具调用轮数

管道输入示例：

# Linux / macOSgitdiff--no-ext-diff|claude-p"审查这份 diff，按严重程度列出问题"# PowerShellGet-Content .\build.log|claude-p"分析构建失败的根因"

核心参数：-p / --print= 非交互模式；--max-turns N= 防止 CI 无限扩大任务；--verbose= 逐轮完整日志（排障用）

6.2 模型、目录与权限

claude--modelsonnet# 指定模型claude --add-dir../shared../docs# 增加可访问目录claude --permission-mode plan# 计划模式：只出方案不改文件claude-p--allowed-tools"Bash(git diff *)"Read"审查当前改动"# 白名单工具

权限模式可选值：default/acceptEdits/plan/bypassPermissions

--dangerously-skip-permissions跳过全部权限确认，仅适用于隔离且可回滚的环境，不要在日常开发中使用。

6.3 系统提示与代理能力

claude --append-system-prompt"所有结论都要引用文件路径和行号"claude-p--append-subagent-system-prompt"每个子代理都必须先阅读 CLAUDE.md""审查认证模块"claude--agentreviewer

这些是临时追加能力，不应替代可版本控制的 CLAUDE.md 和权限配置文件。

七、配置文件体系

7.1 配置作用域与优先级

优先级排序：Managed > 命令行参数 > Local > Project > User

7.2 settings.json 示例（项目级）

{"permissions":{"allow":["Read","Grep","Glob","Bash(git status *)","Bash(git diff *)","Bash(pnpm test *)"],"deny":["Bash(rm -rf *)","Bash(git push --force *)"],"additionalDirectories":["../shared"]},"env":{"CLAUDE_CODE_GIT_BASH_PATH":"C:\\Program Files\\Git\\bin\\bash.exe"},"autoUpdatesChannel":"stable"}

JSON 中 Windows 路径反斜杠需转义（\\）。不要将 API Key 放入项目设置。

7.3 CLAUDE.md（项目指令文件）

CLAUDE.md 是项目级行为规范，建议包含：启动/构建/测试命令、目录职责、编码风格、必跑检查、禁区规则、PR 规范。

# Project Instructions - 使用 Java 21 和 Maven Wrapper - 修改 Java 代码后必须运行 ./mvnw test - 不要修改生产环境配置，不要提交任何密钥 - 编辑前先梳理调用链路与现有测试 - 最终回复列出修改文件与验证命令

重要边界：CLAUDE.md 是行为指令，不是安全边界。安全保障依赖权限策略、托管策略、CI 隔离和密钥管理。

7.4 更新策略配置

claude update# 手动触发更新

{"autoUpdatesChannel":"stable","minimumVersion":"2.1.100"}

禁用后台自动更新：

{"env":{"DISABLE_AUTOUPDATER":"1"}}

八、MCP（Model Context Protocol）

8.1 基础管理命令

claude mcp list# 列出已注册 MCP 服务器claude mcp get SERVER_NAME# 查看指定服务器详情claude mcp remove SERVER_NAME# 移除注册

8.2 四种连接方式

远程 HTTP：

claude mcpadd--transporthttp github https://example.com/mcp

本地 stdio：

claude mcpadd--transportstdio my-tool -- npx-ymy-mcp-server

--是分隔符：左侧为 Claude Code 参数，右侧为 MCP 服务器启动参数

JSON 直接配置：

claude mcp add-json weather-api'{"type":"stdio","command":"weather-cli","args":["--json"]}'

8.3 作用域与安全

MCP 配置支持 local / project / user 三级作用域。团队共享前必须审查.mcp.json中的命令、参数、环境变量、网络与文件权限。凭据必须放在 user / local 配置中，不要提交到项目仓库。

风险提示：MCP Server 与 Claude Code 具备同等高风险操作能力，安装来源务必可信。

九、GitHub Actions 集成

name:Claude Taskon:issues:types:[opened]issue_comment:types:[created]jobs:claude:runs-on:ubuntu-latestpermissions:contents:writeissues:writepull-requests:writesteps:-uses:actions/checkout@v4-uses:anthropics/claude-code-action@v1with:anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}prompt:"审查当前改动；运行测试；只修复确认的错误"claude_args:"--max-turns 5 --model sonnet"

CI 安全原则：严格限制max-turns、工具集合、可写目录；API Key 通过 GitHub Secrets 注入，不要硬编码。

十、企业认证与网络代理

10.1 企业认证方式

支持 Bedrock、Google Cloud / Vertex、Microsoft Foundry 等云厂商部署。不要混用 Anthropic API、Console、Bedrock、Vertex 的认证方式。

10.2 代理配置

exportHTTPS_PROXY=https://proxy.example.com:8080exportHTTP_PROXY=http://proxy.example.com:8080exportSSL_CERT_FILE=/path/to/certificate-bundle.crtexportNODE_EXTRA_CA_CERTS=/path/to/certificate-bundle.crt

当前官方不支持 NO_PROXY 和 SOCKS 代理。防火墙需放行：api.anthropic.com、statsig.anthropic.com、sentry.io（遥测可按企业策略决定是否启用）。

十一、安全最佳实践

1. 默认使用default或plan模式，审查计划后再允许写文件
2. 用 deny 规则封禁高危操作：强制 push、递归删除、生产配置修改
3. CI 遵循最小权限：最小工具集合 + 最小 GitHub permissions
4. 生产凭据工作区禁用--dangerously-skip-permissions
5. 使用隔离分支 / worktree，所有修改经 Diff → 测试 → 人工审查三道关
6. MCP 安装前必审：来源、命令、网络权限、文件权限、Token 安全
7. CLAUDE.md 中不要写入密钥
8. 提示词明确边界：“不要修改未授权文件”、“运行指定测试”、“报告未验证风险”

十二、推荐工作流

进入项目 → claude → 调查结构与约束 → /plan 或 --permission-mode plan → 审查计划与拟修改文件清单 → 小批量分步修改 → 运行测试 / lint / 构建 → git diff / git status 自查 → 人工审查后提交

标准提示词模板：

请先阅读 CLAUDE.md 和相关测试，不要立即修改文件。 【目标】<具体目标> 【范围】<允许修改的目录或文件> 【约束】<兼容性、性能、安全要求> 【验证】完成后运行 <命令>，并报告失败原因。 【输出】先给出实施计划；执行后列出修改文件、测试结果和未验证风险。

十三、排障速查表

十四、最小验收清单

部署完成后依次执行，确认环境健康：

claude--version# 1. 版本号正常显示claude doctor# 2. 诊断无关键错误claude-p"概括项目入口，不修改文件"--permission-mode plan# 3. 计划模式正常工作gitstatus--short# 4. 工作区状态符合预期（未被意外修改）

十五、官方文档导航

十六、核心术语表