Claude Code 安装手册

本手册介绍在 Windows、macOS 与 Linux 上安装和使用 Claude Code。请仅在已获授权的项目、代码库和数据范围内使用，并遵守组织的数据安全与访问控制要求。

1. Claude Code 简介

Claude Code 是 Anthropic 提供的命令行编码助手，可在项目目录中协助理解代码、修改文件、执行经确认的命令以及处理 Git 工作流。它会访问网络完成身份验证和模型请求，因此使用前应确认网络、订阅或 API 账户权限。

2. 系统要求

安装前检查：

node --version
npm --version
git --version

若 Node.js 版本低于 18，请先从 Node.js 官网 安装当前 LTS 版本。

3. Windows 安装

3.1 推荐方式：WSL

1. 以管理员身份打开 PowerShell，安装 WSL：

wsl --install

1. 重启后完成 Ubuntu 初始化，设置 Linux 用户名和密码。
2. 在 Ubuntu 终端内安装 Node.js 18+，确保 node 与 npm 指向 Linux 路径，而不是 /mnt/c/ 下的 Windows 程序。
3. 进入项目目录，例如：

cd /mnt/c/Projects/my-project

1. 按第 5 节安装 Claude Code。

3.2 原生 Windows：Git Bash

安装 Git for Windows 和 Node.js LTS 后，从 Git Bash 中执行第 5 节命令。

如果使用便携版 Git，需指定 Bash 路径：

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

建议将该变量按企业终端管理规范配置，不要随意引用未知来源的 bash.exe。

4. macOS / Linux 准备 Node.js

建议使用系统包管理器、nvm 或组织批准的 Node.js 分发方式安装 Node.js LTS。以 Ubuntu/Debian 为例：

sudo apt update
sudo apt install -y nodejs npm git
node --version

系统仓库的 Node.js 版本可能偏旧；若不满足 18+，请改用 Node.js 官方安装方式或 nvm。

5. 安装 Claude Code

在普通用户终端中执行：

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

不要使用 sudo npm install -g。它可能导致权限混乱和安全风险。

验证安装与诊断：

claude --version
claude doctor

如遇 npm 全局目录权限错误，优先调整 npm 全局目录或使用 Node 版本管理器，不建议通过 sudo 绕过。

6. 登录与首次运行

进入一个已授权的项目目录：

cd /path/to/your-project
claude

根据交互提示选择并完成登录。常见认证方式包括：

• Anthropic Console 账户（需要具备可用计费权限）。
• Claude App 的 Pro 或 Max 订阅账户。
• 企业环境的 Amazon Bedrock 或 Google Vertex AI 集成。

不要把 API Key、访问令牌或企业凭据写入 Git 仓库、Shell 历史、脚本或 Markdown 文档。

7. 常用命令

# 进入交互模式
claude

# 带初始问题启动
claude "解释当前项目的目录结构"

# 输出一次结果后退出，适用于脚本调用
claude -p "检查本项目是否存在明显的类型错误"

# 继续最近一次会话
claude -c

# 更新到最新版本
claude update

# 检查运行环境和安装状态
claude doctor

使用时应先从只读分析开始。对文件修改、依赖安装、运行命令或 Git 操作，应检查 Claude Code 显示的操作范围并按需确认。

8. 企业代理与网络配置

Claude Code 支持标准 HTTP/HTTPS 代理环境变量：

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

注意事项：

• 不要把代理用户名和密码直接写入共享脚本。
• 当前 Claude Code 不支持 NO_PROXY，配置代理后流量会经由代理。
• 不支持 SOCKS 代理。
• 防火墙或代理白名单通常需允许 api.anthropic.com、statsig.anthropic.com 和 sentry.io。

9. 安全与团队使用建议

• 在项目根目录检查 .gitignore，避免令牌、密钥、生产配置被提交。
• 不要让工具读取超出当前任务范围的目录；需要时使用受控工作目录。
• 对生产脚本、基础设施定义和数据库迁移，先审阅变更再执行。
• 企业使用应结合 SSO、代理审计、密钥管理、最小权限和数据分类制度。
• 若通过 LiteLLM 等第三方网关接入，应由团队统一管理端点、认证、预算和审计；不要使用来源不明的网关。

10. 常见问题

claude: command not found

关闭并重新打开终端，确认 npm 的全局 bin 目录已加入 PATH，然后执行：

npm prefix -g
claude doctor

WSL 中找不到 Node.js

检查：

which node
which npm

两者应优先指向 Linux 路径，如 /usr/bin/ 或 nvm 安装目录，而不是 /mnt/c/ 下的 Windows 路径。

企业网络下认证或请求失败

检查代理地址、DNS、证书链和出口白名单；不要通过关闭 TLS 校验来绕过证书问题。参考 Anthropic 的企业代理文档。

11. 官方参考

• Claude Code 官方入门与安装
• Claude Code CLI 命令参考
• Claude Code 企业代理配置
• Claude Code LLM Gateway 配置