个人主页编程的一拳超人⛺️ 欢迎关注点赞 留言 收藏 于高山之巅方见大河奔涌于群峰之上更觉长风浩荡。Claude Code 安装、配置、依赖与使用说明书版本基准2026-07-22 Anthropic 官方文档重要提示Claude Code 更新频繁部署前务必执行claude doctor并复核官方页面一、产品形态与选型Claude Code 是 Anthropic 面向软件开发的智能编码 Agent具备代码读写、文件搜索、测试执行、Git 操作能力并可通过 MCP 协议接入外部工具。形态入口适用场景是否需单独安装 CLICLI 交互终端claude日常开发、重构、调试、代码审查需要CLI 非交互claude -p脚本调用、CI 流水线、批处理需要DesktopClaude 桌面应用多会话并行、可视化 Diff、集成终端应用自带VS Code / CursorIDE 扩展编辑器内对话、代码引用、审查计划扩展自带终端执行仍需 CLIJetBrainsIDE 集成Java / Kotlin / Android 生态按 IDE 文档操作Web / 远程Claude Code on the Web云端执行、跨设备续作按页面连接GitHub Actions工作流 ActionIssue / PR 自动实现与审查Runner 直接调用 ActionAgent 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 / CMDmacOS / 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.jsGit 不是启动硬性依赖但开发项目建议安装。不要盲目预装所有语言环境按需安装即可。2.2 Git 的作用与安装验证Git是源代码版本管理工具。Claude Code 在无 Git 的目录中也能读写文件但 Git 能提供变更审查、分支隔离、误改回滚、Diff 分析等关键能力。Ubuntu / Debian 安装命令sudoaptupdate# 更新软件源索引sudoaptinstallgit# 安装 Gitgit--version# 验证安装版本gitconfig--globaluser.nameYour Name# 设置全局提交用户名gitconfig--globaluser.emailyouexample.com# 设置全局提交邮箱技术标注sudo 以管理员权限执行--global 当前用户全局生效仅为单项目配置时去掉该参数。2.3 Node.js 依赖边界澄清原生安装器不依赖 Node.js。仅以下三种情况需要 Node.js / npm选择 npm 全局安装方式目标项目本身是 Node.js 项目项目构建/测试/格式化命令依赖 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 的统一前置依赖仅在执行对应项目命令时才需要。项目类型常见额外工具PythonPython、pip / uv、虚拟环境工具Java / KotlinJDK、Maven 或 GradleNode.jsNode.js、npm / pnpm / yarnGoGo toolchainRustRust toolchain、Cargo容器化项目Docker 或兼容容器运行时大文件仓库Git LFS2.5 系统要求与平台差异官方支持矩阵系统版本macOS 13、Windows 10 1809 / Server 2019、Ubuntu 20.04、Debian 10、Alpine 3.19硬件要求至少 4 GB RAM支持 x64 / ARM64 架构网络要求需可访问 Anthropic 服务Windows 双路线说明原生 WindowsPowerShell / CMD 安装适配 Windows 原生工具链WSL 1 / 2WSL 终端内安装适配 Linux 工具链 —— 注意不要混用 Windows 路径与 WSL 路径账号权限说明Pro / Max、Teams / Enterprise、Console 账号可用免费 Claude.ai 账号不含 Claude Code 权限。不要将 API Key 提交到 Git、写入 CLAUDE.md 或聊天记录中。三、安装方式3.1 原生安装器推荐macOS / Linux / WSLcurl-fsSLhttps://claude.ai/install.sh|bash参数拆解-f遇 HTTP 错误直接失败-s静默模式-S静默时仍显示错误-L跟随重定向Windows PowerShellirmhttps://claude.ai/install.ps1|iex参数拆解irm Invoke-RestMethod 别名iex Invoke-Expression 别名无需管理员权限Windows CMDcurl -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 HomebrewmacOSbrewinstall--caskclaude-code# 安装brew upgrade claude-code# 升级brew uninstall--caskclaude-code# 卸载claude-code跟随 stable 频道claude-codelatest跟随 latest 频道。Homebrew 版本不由 Claude Code 自动升级更新可能略滞后。3.3 WinGetWindowswinget install Anthropic.ClaudeCode# 安装winget upgrade Anthropic.ClaudeCode# 升级winget uninstall Anthropic.ClaudeCode# 卸载3.4 Debian / Ubuntuapt 仓库# 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. 添加软件源echodeb [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升级与卸载sudoaptupdatesudoaptupgrade claude-code# 升级sudoaptremove claude-code# 卸载3.5 Fedora / RHELdnf 仓库# 添加 yum 仓库配置sudotee/etc/yum.repos.d/claude-code.repoEOF [claude-code] nameClaude Code baseurlhttps://downloads.claude.ai/claude-code/rpm/stable enabled1 gpgcheck1 gpgkeyhttps://downloads.claude.ai/keys/claude-code.asc EOFsudodnfinstallclaude-code# 安装sudodnf upgrade claude-code# 升级sudodnf remove claude-code# 卸载3.6 Alpine Linuxapk# 导入公钥wget-O/etc/apk/keys/claude-code.rsa.pub https://downloads.claude.ai/keys/claude-code.rsa.pub# 添加仓库源echohttps://downloads.claude.ai/claude-code/apk/stable/etc/apk/repositories# 安装与升级apkaddclaude-code apk updateapk upgrade claude-codeAlpine 额外依赖bash、curl、libgcc、libstdc、ripgrep。musl 环境搜索异常时在 settings 中配置{env:{USE_BUILTIN_RIPGREP:0}}3.7 npm 全局安装npminstall-ganthropic-ai/claude-code# 安装稳定版npminstall-ganthropic-ai/claude-codelatest# 安装最新版版本要求自 2.1.198 起要求 Node.js 22且包管理器需支持 optional dependencies。适用场景已有 Node.js 版本管理体系的团队新部署优先选择原生安装器。3.8 Desktop、IDE 与远程形态Desktop适合不熟悉终端、需要多会话并行、可视化 Diff / 预览的用户VS Code 扩展要求 VS Code 1.94扩展面板自带 CLI若在集成终端执行claude仍需单独安装 CLIJetBrains 集成适配 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继续完成剩余工作# 恢复并立即追加任务常用斜杠命令速查表命令用途/help查看帮助/clear清空当前上下文/compact压缩长会话上下文/model查看 / 切换模型/config打开设置面板支持/config keyvalue直接修改/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-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-toolsBash(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 配置作用域与优先级作用域位置说明ManagedIT 系统策略 / 注册表 / managed-settings.json企业强制策略优先级最高不可覆盖User~/.claude/个人跨项目偏好Project仓库.claude/团队共享规则可提交 GitLocal.claude/settings.local.json当前用户当前项目通常不提交优先级排序Managed 命令行参数 Local Project User7.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}}八、MCPModel Context Protocol8.1 基础管理命令claude mcp list# 列出已注册 MCP 服务器claude mcp get SERVER_NAME# 查看指定服务器详情claude mcp remove SERVER_NAME# 移除注册8.2 四种连接方式远程 HTTPclaude mcpadd--transporthttp github https://example.com/mcp本地 stdioclaude 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/checkoutv4-uses:anthropics/claude-code-actionv1with:anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}prompt:审查当前改动运行测试只修复确认的错误claude_args:--max-turns 5 --model sonnetCI 安全原则严格限制max-turns、工具集合、可写目录API Key 通过 GitHub Secrets 注入不要硬编码。十、企业认证与网络代理10.1 企业认证方式支持 Bedrock、Google Cloud / Vertex、Microsoft Foundry 等云厂商部署。不要混用 Anthropic API、Console、Bedrock、Vertex 的认证方式。10.2 代理配置exportHTTPS_PROXYhttps://proxy.example.com:8080exportHTTP_PROXYhttp://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遥测可按企业策略决定是否启用。十一、安全最佳实践默认使用default或plan模式审查计划后再允许写文件用 deny 规则封禁高危操作强制 push、递归删除、生产配置修改CI 遵循最小权限最小工具集合 最小 GitHub permissions生产凭据工作区禁用--dangerously-skip-permissions使用隔离分支 / worktree所有修改经 Diff → 测试 → 人工审查三道关MCP 安装前必审来源、命令、网络权限、文件权限、Token 安全CLAUDE.md 中不要写入密钥提示词明确边界“不要修改未授权文件”、“运行指定测试”、“报告未验证风险”十二、推荐工作流进入项目 → claude → 调查结构与约束 → /plan 或 --permission-mode plan → 审查计划与拟修改文件清单 → 小批量分步修改 → 运行测试 / lint / 构建 → git diff / git status 自查 → 人工审查后提交标准提示词模板请先阅读 CLAUDE.md 和相关测试不要立即修改文件。 【目标】具体目标 【范围】允许修改的目录或文件 【约束】兼容性、性能、安全要求 【验证】完成后运行 命令并报告失败原因。 【输出】先给出实施计划执行后列出修改文件、测试结果和未验证风险。十三、排障速查表现象处理方案claude命令找不到重开终端 → 检查 PATH → 运行claude doctornpm 安装权限错误不要使用sudo npm修复 npm 目录权限或改用原生安装器Windows 找不到 Bash安装 Git for Windows配置CLAUDE_CODE_GIT_BASH_PATH登录循环 / 403检查账号、代理、防火墙、系统时间SSH/WSL 用复制 URL codeMCP 不工作/mcp查看状态 →claude mcp list/get→ 检查命令与环境变量高 CPU / 内存占用/compact→ 重启 →claude --safe-mode排除插件冲突搜索不到文件检查.gitignore、文件权限、ripgrepAlpine 设USE_BUILTIN_RIPGREP0配置不生效检查作用域优先级、JSON 语法 →claude doctor验证CI 成本失控限制--max-turns→ 固定模型 → 收敛工具范围 → 拆分任务十四、最小验收清单部署完成后依次执行确认环境健康claude--version# 1. 版本号正常显示claude doctor# 2. 诊断无关键错误claude-p概括项目入口不修改文件--permission-mode plan# 3. 计划模式正常工作gitstatus--short# 4. 工作区状态符合预期未被意外修改十五、官方文档导航文档页面适用场景安装与高级设置选择安装器、系统要求、版本频道、升级卸载CLI 完整参考子命令与参数大全比claude --help更完整交互模式快捷键、输入模式、会话操作设置与配置settings.json、作用域、优先级、环境变量权限系统allow/deny 规则、权限模式、工具策略认证与 IAM登录、Console、Teams/Enterprise、云厂商身份MCP 协议本地/远程连接、OAuth、作用域、故障处理Desktop 桌面端多会话、并行工作、SSH、企业控制IDE 集成VS Code、Cursor、JetBrains、终端切换GitHub ActionsPR/Issue 自动化、Secret、权限、参数企业部署Bedrock、Google Cloud、Microsoft FoundryAgent SDKPython / TypeScript 程序化构建 Agent常见工作流代码理解、测试、重构、审查范式故障排查性能、卡顿、搜索、配置问题十六、核心术语表名词全称 / 含义在 Claude Code 中的作用CLICommand Line Interface终端claude命令交互入口REPLRead-Eval-Print Loop交互式持续对话界面Agent智能代理理解任务、调用工具、多轮执行的程序Tool工具Read / Edit / Bash / Grep 等可调用能力MCPModel Context Protocol标准化接入外部 API、数据库、应用工具MCP ServerMCP 服务端对外暴露工具/资源/提示词的程序stdioStandard Input/Output本机 MCP 进程通信方式OAuth授权协议浏览器登录远程服务无需交密码给客户端API KeyAPI 访问密钥机器调用凭据不要入库ConsoleAnthropic Console企业级 API 计费与密钥管理入口CLAUDE.md项目指令文件项目规范、命令、限制、验证方式说明Settings设置文件权限、环境变量、MCP、模型等配置Scope配置作用域企业 / 个人 / 项目 / 本机的生效层级Permission Mode权限模式控制工具调用是否需要人工确认Hook钩子会话生命周期触发的脚本Subagent子代理独立子任务的专门代理WorktreeGit 工作树同仓库多隔离目录并行开发stable / latest发布频道stable 保守稳定latest 功能最新