Claude Code 安装部署与使用指南
|
AI / LLM

适用对象：想在终端、VS Code 中使用 Claude Code 的开发者。
说明：本文以官方文档为基础整理，覆盖安装、登录、VS Code 集成、常见命令、更新与排错。

1. Claude Code 是什么

Claude Code 是一个代理式编码工具，可以读取代码库、编辑文件、运行命令，并集成到终端和 IDE 中使用。

它常见的使用方式包括：

  • 终端 CLI
  • VS Code 扩展
  • Desktop App
  • Web
  • JetBrains 插件

2. 使用前提

在大多数场景下，你需要：

  • 一个可用的 Claude / Anthropic 账号
  • 或者企业/团队账号
  • 某些场景下也可以使用第三方提供商，例如 Amazon Bedrock、Google Vertex AI、Microsoft Foundry

注意：终端 CLI 和 VS Code 也支持第三方提供商；如果你是直接连接 Anthropic 官方账号，通常首次启动会走浏览器登录流程。

3. 安装方式

3.1 推荐安装方式

Claude Code 官方提供原生安装方式，支持 macOS、Linux、WSL、Windows。

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

3.2 Homebrew

brew install --cask claude-code

说明：Homebrew 提供两个 cask：

  • claude-code：稳定通道
  • claude-code@latest：最新通道

Homebrew 安装后不会自动更新，需要手动执行升级。

3.3 WinGet

winget install Anthropic.ClaudeCode

WinGet 安装后也不会自动更新，需要手动升级。

3.4 npm 全局安装

如果你更习惯 Node 生态，也可以用 npm 全局安装：

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

升级 npm 安装建议使用：

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

不要用 npm update -g 来期望直接切到最新版本。

3.5 平台说明

npm 安装依赖可选平台二进制，常见支持平台包括：

  • darwin-arm64
  • darwin-x64
  • linux-x64
  • linux-arm64
  • linux-x64-musl
  • linux-arm64-musl
  • win32-x64
  • win32-arm64

如果安装后找不到二进制，通常要检查包管理器是否允许 optional dependencies。

4. 安装后检查

安装完成后，先确认版本：

claude --version

再做一次环境诊断：

claude doctor

如果出现 command not found、权限错误、找不到二进制等问题，优先检查 PATH、安装方式、Node/npm 版本和权限。

5. 第一次登录

5.1 官方账号登录

首次运行：

claude

然后按提示登录。一般会自动打开浏览器完成认证。

如果浏览器没有自动打开，通常可以在终端里复制登录链接再手动打开。

5.2 退出登录

在 Claude Code 提示符里执行：

/logout

5.3 查看登录状态

claude auth status

5.4 重新登录

claude auth login

也可以按需使用：

claude auth login --console
claude auth login --sso
claude auth login --email [email protected]

6. 你提到的“disable login prompt”

如果你在 VS Code 中使用第三方提供商，官方文档建议在扩展里关闭登录提示。

操作思路：

  1. 打开 VS Code 设置
  2. 搜索 Claude Code login
  3. 勾选 Disable Login Prompt

这个设置常用于以下情况：

  • 你不是直接登录 Claude 官方账号
  • 你走 Bedrock / Vertex AI / Foundry
  • 你希望 VS Code 扩展不强制弹出官方登录流程

7. VS Code 集成

7.1 安装扩展

在 VS Code 扩展市场搜索并安装 Claude Code。

也可以在扩展视图中直接搜索：

  • Claude Code

7.2 使用入口

安装后，常见打开方式有：

  • 编辑器右上角的 Spark 图标
  • 左侧 Activity Bar 的 Spark 图标
  • 命令面板中搜索 Claude Code
  • 右下角状态栏入口

7.3 VS Code 里能做什么

  • 内联差异查看
  • @-mention 当前文件/选区
  • 计划审查
  • 会话历史
  • 与 Git 工作流结合

7.4 VS Code 扩展与 CLI 的关系

扩展自带一份 CLI 组件用于面板聊天；如果你要在 VS Code 集成终端里直接运行 claude，仍然建议安装独立 CLI。

7.5 在 VS Code 里调用 CLI

在 VS Code 终端里直接运行：

claude

如果你使用第三方提供商，则先配置对应环境或设置，再启动。

8. 基本使用方式

8.1 进入交互会话

claude

8.2 带初始问题启动

claude "explain this project"

8.3 直接查询后退出

claude -p "explain this function"

8.4 处理管道输入

cat logs.txt | claude -p "summarize these logs"

8.5 继续上一次会话

claude -c

8.6 指定会话继续

claude -r "auth-refactor"

8.7 安全模式 / 调试模式

claude --safe-mode
claude --debug

9. 常见命令速查

9.1 认证相关

claude auth login
claude auth login --console
claude auth logout
claude auth status

9.2 会话相关

claude
claude "query"
claude -c
claude -r "session-id-or-name"
claude --resume "session-id-or-name"
claude --name "my-feature-work"

9.3 更新与安装

claude update
claude install stable
claude install latest

9.4 诊断相关

claude doctor
claude --debug
claude --debug-file /tmp/claude-debug.log

9.5 权限与工具控制

claude --disable-slash-commands
claude --dangerously-skip-permissions
claude --allowed-tools "Read" "Edit"
claude --disallowed-tools "Bash(rm *)"

10. 常用交互命令

在 Claude Code 的交互界面中，常会用到这些命令：

  • /help：查看帮助
  • /status：查看当前状态
  • /logout：退出当前账号
  • /rename：重命名当前会话
  • /mcp：管理 MCP
  • /add-dir：添加额外工作目录

不同版本的交互命令可能略有差异，建议以 claude --help、/help 和官方文档为准。

11. 适合开发时的典型工作流

11.1 修 bug

claude "定位这个报错并修复，顺便补测试"

11.2 写测试

claude "给 auth 模块补单元测试并执行"

11.3 处理 Git 提交

claude "把当前修改整理成一个清晰的 commit"

11.4 代码审查

claude "review 这个分支的改动，指出风险点"

12. 更新方式

12.1 原生安装更新

原生安装会自动后台更新到最新版。

12.2 Homebrew 更新

brew upgrade claude-code
# 或
brew upgrade claude-code@latest

12.3 WinGet 更新

winget upgrade Anthropic.ClaudeCode

12.4 npm 更新

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

13. 卸载方式

13.1 npm 卸载

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

13.2 Homebrew 卸载

brew uninstall --cask claude-code

13.3 WinGet 卸载

winget uninstall Anthropic.ClaudeCode

13.4 VS Code 扩展卸载

在扩展视图里卸载 Claude Code 扩展即可。

14. 第三方提供商场景

如果组织使用以下平台之一：

  • Amazon Bedrock
  • Google Vertex AI
  • Microsoft Foundry

通常流程是：

  1. 在 VS Code 里关闭登录提示
  2. 配置对应平台凭据和环境变量
  3. 让 ~/.claude/settings.json 统一保存设置
  4. CLI 和 VS Code 扩展共用配置

14.1 Bedrock / Vertex AI / Foundry 的共性

  • 先准备云端账号和权限
  • 再配置 CLI / 扩展
  • 最后在 Claude Code 里走第三方登录或环境变量接入

15. 常见问题排查

15.1 claude 命令找不到

检查：

  • 是否真的安装成功
  • npm 全局目录是否在 PATH
  • PowerShell / CMD / Bash 是否混用
  • 是否需要重新打开终端

15.2 登录页打不开

检查：

  • 浏览器是否被拦截
  • 网络是否正常
  • 企业代理 / 防火墙是否限制
  • 是否需要手动复制登录链接

15.3 VS Code 扩展连不上

检查：

  • VS Code 版本是否满足要求
  • 扩展是否正确安装
  • 是否已经关闭登录提示并切换到第三方提供商
  • CLI 是否已在系统中可用

15.4 安装后找不到二进制

常见原因：

  • 包管理器禁用了 optional dependencies
  • 权限不足
  • npm 安装未成功完成
  • 平台架构不匹配

15.5 权限问题

不要直接依赖 sudo npm install -g 作为首选方案。优先考虑修正 npm 全局目录权限或使用更合适的安装方式。

16. 实战建议

  • 终端里先把 Claude Code 跑通，再接 VS Code
  • 项目级操作尽量在仓库根目录执行
  • 长任务建议先让它规划，再逐步执行
  • 修改前先让它说明方案，修改后再让它复查
  • 重要项目建议配合 Git worktree / 分支隔离

17. 一个适合直接复制的最小启动流程

# 安装
npm install -g @anthropic-ai/claude-code

# 检查版本
claude --version

# 进入项目
cd your-project

# 启动
claude

18. 一个适合 VS Code 的最小启动流程

  1. 安装 Claude Code 扩展
  2. 打开项目
  3. 需要时在设置中关闭 Disable Login Prompt
  4. 配置第三方提供商或直接登录官方账号
  5. 点击 Spark 图标或用命令面板打开 Claude Code 面板

19. 推荐保留的命令清单

claude
claude --version
claude doctor
claude auth status
claude auth login
claude auth logout
claude update
claude -c
claude -r "session-name"
claude --safe-mode

20. 备注

  • 官方文档会持续更新，参数和菜单项可能随版本变化
  • 你在不同系统里看到的登录提示、按钮名称、菜单入口，可能会略有不同
  • 如果你是企业环境，优先以组织的登录方式、权限策略和安全要求为准
上一篇
下一篇