在这里插入图片描述

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

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

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

分割线

分割线2

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

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

一、产品形态与选型

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

形态 入口 适用场景 是否需单独安装 CLI
CLI 交互 终端 claude 日常开发、重构、调试、代码审查 需要
CLI 非交互 claude -p 脚本调用、CI 流水线、批处理 需要
Desktop Claude 桌面应用 多会话并行、可视化 Diff、集成终端 应用自带
VS Code / Cursor IDE 扩展 编辑器内对话、代码引用、审查计划 扩展自带；终端执行仍需 CLI
JetBrains IDE 集成 Java / Kotlin / Android 生态 按 IDE 文档操作
Web / 远程 Claude Code on the Web 云端执行、跨设备续作 按页面连接
GitHub Actions 工作流 Action Issue / PR 自动实现与审查 Runner 直接调用 Action
Agent SDK 程序调用 构建内部自动化平台 按 SDK 安装

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

二、安装前准备

2.1 依赖项全景判断

依赖项 必需性 说明
支持的操作系统 必须 macOS、Windows、Ubuntu、Debian、Alpine 等
终端环境 必须 Windows PowerShell / CMD；macOS / Linux Terminal
网络连接 必须 登录与模型服务均需联网
Anthropic 有效账号 必须 首次启动时完成登录授权
Git 强烈建议 查看 Diff、创建分支、回滚修改、项目管理
Node.js / npm 仅 npm 安装需要 原生安装器、Homebrew、WinGet、apt/dnf/apk 均不需要
Python / Java / Go / Rust / Docker 按项目需要 仅 Claude 需运行对应项目构建/测试时才安装
VS Code / JetBrains 可选 IDE 集成不是 CLI 的硬性依赖

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

2.2 Git 的作用与安装验证

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

Ubuntu / Debian 安装命令：

sudo apt update          # 更新软件源索引
sudo apt install git     # 安装 Git
git --version            # 验证安装版本
git config --global user.name "Your Name"    # 设置全局提交用户名
git config --global user.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 版本
npm config get prefix    # 查看 npm 全局安装目录（排查 PATH 问题用）

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

2.4 项目运行时 ≠ Claude Code 依赖

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

项目类型 常见额外工具
Python Python、pip / uv、虚拟环境工具
Java / Kotlin JDK、Maven 或 Gradle
Node.js Node.js、npm / pnpm / yarn
Go Go toolchain
Rust Rust toolchain、Cargo
容器化项目 Docker 或兼容容器运行时
大文件仓库 Git LFS

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 -fsSL https://claude.ai/install.sh | bash

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

Windows PowerShell：

irm https://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 / Linux
curl -fsSL https://claude.ai/install.sh | bash -s stable

# PowerShell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

安装指定版本：

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

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

3.2 Homebrew（macOS）

brew install --cask claude-code    # 安装
brew upgrade claude-code           # 升级
brew uninstall --cask claude-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. 创建密钥目录
sudo install -d -m 0755 /etc/apt/keyrings

# 2. 导入签名密钥
sudo curl -fsSL https://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" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list

# 4. 刷新索引并安装
sudo apt update
sudo apt install claude-code

升级与卸载：

sudo apt update && sudo apt upgrade claude-code   # 升级
sudo apt remove claude-code                        # 卸载

3.5 Fedora / RHEL（dnf 仓库）

# 添加 yum 仓库配置
sudo tee /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
EOF

sudo dnf install claude-code    # 安装
sudo dnf upgrade claude-code    # 升级
sudo dnf 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

# 安装与升级
apk add claude-code
apk update && apk upgrade claude-code

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

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

3.7 npm 全局安装

npm install -g @anthropic-ai/claude-code          # 安装稳定版
npm install -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 / Linux
export ANTHROPIC_API_KEY="你的密钥"
claude -p "解释这个项目的构建流程"

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

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

五、交互式使用

启动会话：

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

恢复会话：

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

常用斜杠命令速查表：

命令 用途
/help 查看帮助
/clear 清空当前上下文
/compact 压缩长会话上下文
/model 查看 / 切换模型
/config 打开设置面板，支持 /config key=value 直接修改
/permissions 管理工具权限
/mcp 查看 MCP 连接状态
/doctor 会话内运行诊断
/status 查看当前会话状态
/cost 查看用量与成本
/resume 选择历史会话恢复
/exit 或 Ctrl-D 退出会话

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

六、CLI 参数详解

6.1 非交互与输出控制

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

管道输入示例：

# Linux / macOS
git diff --no-ext-diff | claude -p "审查这份 diff，按严重程度列出问题"

# PowerShell
Get-Content .\build.log | claude -p "分析构建失败的根因"

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

6.2 模型、目录与权限

claude --model sonnet                                # 指定模型
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 --agent reviewer

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

七、配置文件体系

7.1 配置作用域与优先级

作用域 位置 说明
Managed IT 系统策略 / 注册表 / managed-settings.json 企业强制策略，优先级最高，不可覆盖
User ~/.claude/ 个人跨项目偏好
Project 仓库 .claude/ 团队共享规则，可提交 Git
Local .claude/settings.local.json 当前用户当前项目，通常不提交

优先级排序：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 mcp add --transport http github https://example.com/mcp

本地 stdio：

claude mcp add --transport stdio my-tool -- npx -y my-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 Task
on:
  issues:
    types: [opened]
  issue_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          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 代理配置

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export SSL_CERT_FILE=/path/to/certificate-bundle.crt
export NODE_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 命令找不到 重开终端 → 检查 PATH → 运行 claude doctor
npm 安装权限错误 不要使用 sudo npm；修复 npm 目录权限或改用原生安装器
Windows 找不到 Bash 安装 Git for Windows，配置 CLAUDE_CODE_GIT_BASH_PATH
登录循环 / 403 检查账号、代理、防火墙、系统时间；SSH/WSL 用复制 URL + code
MCP 不工作 /mcp 查看状态 → claude mcp list/get → 检查命令与环境变量
高 CPU / 内存占用 /compact → 重启 → claude --safe-mode 排除插件冲突
搜索不到文件 检查 .gitignore、文件权限、ripgrep；Alpine 设 USE_BUILTIN_RIPGREP=0
配置不生效 检查作用域优先级、JSON 语法 → claude doctor 验证
CI 成本失控 限制 --max-turns → 固定模型 → 收敛工具范围 → 拆分任务

十四、最小验收清单

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

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

十五、官方文档导航

文档页面 适用场景
安装与高级设置 选择安装器、系统要求、版本频道、升级卸载
CLI 完整参考 子命令与参数大全，比 claude --help 更完整
交互模式 快捷键、输入模式、会话操作
设置与配置 settings.json、作用域、优先级、环境变量
权限系统 allow/deny 规则、权限模式、工具策略
认证与 IAM 登录、Console、Teams/Enterprise、云厂商身份
MCP 协议 本地/远程连接、OAuth、作用域、故障处理
Desktop 桌面端 多会话、并行工作、SSH、企业控制
IDE 集成 VS Code、Cursor、JetBrains、终端切换
GitHub Actions PR/Issue 自动化、Secret、权限、参数
企业部署 Bedrock、Google Cloud、Microsoft Foundry
Agent SDK Python / TypeScript 程序化构建 Agent
常见工作流 代码理解、测试、重构、审查范式
故障排查 性能、卡顿、搜索、配置问题

十六、核心术语表

名词 全称 / 含义 在 Claude Code 中的作用
CLI Command Line Interface 终端 claude 命令交互入口
REPL Read-Eval-Print Loop 交互式持续对话界面
Agent 智能代理 理解任务、调用工具、多轮执行的程序
Tool 工具 Read / Edit / Bash / Grep 等可调用能力
MCP Model Context Protocol 标准化接入外部 API、数据库、应用工具
MCP Server MCP 服务端 对外暴露工具/资源/提示词的程序
stdio Standard Input/Output 本机 MCP 进程通信方式
OAuth 授权协议 浏览器登录远程服务，无需交密码给客户端
API Key API 访问密钥 机器调用凭据，不要入库
Console Anthropic Console 企业级 API 计费与密钥管理入口
CLAUDE.md 项目指令文件 项目规范、命令、限制、验证方式说明
Settings 设置文件 权限、环境变量、MCP、模型等配置
Scope 配置作用域 企业 / 个人 / 项目 / 本机的生效层级
Permission Mode 权限模式 控制工具调用是否需要人工确认
Hook 钩子 会话生命周期触发的脚本
Subagent 子代理 独立子任务的专门代理
Worktree Git 工作树 同仓库多隔离目录，并行开发
stable / latest 发布频道 stable 保守稳定；latest 功能最新
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

chatgpt/codex学习分享

飞书链接：https://ycnods7vwqrz.feishu.cn/wiki/M0d3w6xz8ixGcVkoKM9cyWVfnnc 密码：Gin1234567。我已经整理成了飞书文档。

avatar AI编程社区

Dario 常驻 Codex｜从生图到安装，手把手带你换一套 Codex 皮肤

# 总结通过本文，我们从原理上理解了 Codex 皮肤系统如何通过 CSS 注入实现深度定制，并用 Python 生成了 Dario 风格的背景图，最后构建了一个完整的 Codex 扩展。记住，好的皮肤设计不仅要好看，还要考虑代码可读性和性能平衡，这才是技术美学的精髓。而“换皮肤”不仅是外观美化的过程，更涉及到 Codex 的主题系统、CSS 注入机制以及扩展的生命周期管理。## 构建 Codex

avatar AI编程社区

什么是RAG？

的技术。举个例子：你问 ChatGPT："我们公司机器人 SDK 的 TCP 通信协议是什么？

avatar AI编程社区