更新日期：2026-09-27
Claude Code 是 Anthropic 官方的终端 AI 编程工具：它在你的项目目录里运行，能读写代码、执行命令、跑测试、提交 Git，以 Agent 方式完成多步骤的工程任务。本文覆盖从安装到日常维护的完整生命周期——npm 与原生脚本两种安装方式、订阅与 API 两种计费的登录配置、更新与彻底重装、常见安装报错的处理，以及在 Docker/CI 环境中的部署方法。
安装方式以官方文档为准（工具迭代很快），本文按 2026 年 9 月的稳定用法编写，命令都给出验证方法，装完即可开工。
一、安装前的准备：系统要求与账号
操作系统： macOS 与 Linux 原生支持；Windows 官方长期推荐在 WSL2 中使用，较新版本也已提供 Windows 原生支持（PowerShell 环境），原生支持属于较新特性，遇到兼容问题时 WSL2 仍是最稳的选择。
运行时： 走 npm 安装路径需要 Node.js 18 或更高版本（建议 20+ 的 LTS）。检查方式：
node --version
npm --version
账号与计费： 两种模式二选一——
- 订阅模式：Claude Pro 或 Max 订阅账号，登录即用，受订阅用量额度限制，适合个人日常开发；
- API 模式：在 Anthropic Console 创建 API Key，按 token 用量计费，适合团队、CI 和用量波动大的场景。
两种模式可以共存，登录方式在运行时切换。
二、方式一：npm 全局安装（最通用）
这是最经典、文档最全的安装方式：
npm install -g @anthropic-ai/claude-code
安装完成后验证：
claude --version
能打印版本号即安装成功。如果提示 claude: command not found，是 npm 全局 bin 目录不在 PATH 里，见第七节的排障部分。
权限报错的处理。 直接对系统 Node 执行 -g 安装，常见 EACCES: permission denied。正确解法不是 sudo，而是把全局目录改到用户空间：
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH # 写入 ~/.bashrc 或 ~/.zshrc
或者更彻底地用 nvm 管理 Node 版本，nvm 的全局包目录天然在用户目录下，不会有权限问题。用 sudo npm install -g 虽然能装上，但后续 claude update 和 npm 自更新都会遇到权限纠缠，不建议。
三、方式二：原生安装脚本（无 Node 依赖）
Anthropic 提供了不依赖 Node.js 的原生安装方式，macOS 与 Linux 上一条命令：
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell 环境（原生支持）：
irm https://claude.ai/install.ps1 | iex
原生方式把二进制装到用户目录，不依赖系统 Node，也不存在 npm 全局权限问题，是较新的推荐路径。安装脚本会明确提示安装位置；执行前可以先 curl -fsSL https://claude.ai/install.sh | less 审一遍脚本内容——对任何 curl | bash 形式的安装，审计都是好习惯。
两种方式装的是同一个工具，二选一即可。混装（先 npm 又跑原生脚本）可能出现 PATH 里两个 claude 互相覆盖，which claude 确认实际生效的是哪一个。
四、首次启动与登录
Claude Code 以项目为工作单位运行。进入项目目录启动：
cd your-project
claude
首次启动会引导认证：
订阅账号登录。 按提示选择 Claude 账号登录，浏览器打开 OAuth 授权页，确认后回到终端即可。之后可用 /status 查看当前登录的账号与用量状态，/login、/logout 切换账号。
API Key 模式。 在 Anthropic Console（https://console.anthropic.com ）创建 Key 后，通过环境变量提供：
export ANTHROPIC_API_KEY=sk-ant-xxxx
claude
建议写入 ~/.bashrc 或使用 direnv 之类工具按项目加载，不要把 Key 写进项目文件——它会被 git 提交。
启动后先跑一次自检：
claude doctor
它会检查安装完整性、Node 版本、网络连通性，多数"装上了但行为怪异"的问题都能在这里得到线索。
五、更新与版本管理
npm 安装方式：
npm update -g @anthropic-ai/claude-code
原生安装方式：
claude update
Claude Code 默认开启自动更新，会话启动时后台拉取新版本；如果想锁定版本（比如 CI 里保证可复现），安装时指定 npm 版本号即可：npm install -g @anthropic-ai/claude-code@<version>。会话内输入 /status 可以同时看到 CLI 版本，排查问题时这是第一个要报的信息。
六、彻底重装与清理
升级失败、配置损坏或换机器时，按下面的顺序彻底清理再重装：
# npm 方式卸载
npm uninstall -g @anthropic-ai/claude-code
# 清理用户级配置与凭据（包含登录态、项目信任记录、本地设置）
rm -rf ~/.claude
rm -f ~/.claude.json
macOS 上登录凭据还可能存在系统钥匙串中，重装后如果提示凭据异常，在"钥匙串访问"里搜索 Claude 相关条目删除。清理后按第二节或第三节重新安装、第四节重新登录即可。只想保留配置重装工具的话，跳过 rm 步骤，直接安装新版本覆盖。
注意：~/.claude/projects/ 下保存着各项目的历史会话记录，删除前确认不需要回溯。
七、常见安装问题排查
command not found: claude：全局 bin 目录不在 PATH。npm config get prefix 找到前缀，把 <prefix>/bin 加进 PATH；原生安装则确认安装脚本输出的路径已加入 PATH 并重新加载 shell。
EACCES 权限错误：见第二节，改 prefix 或换 nvm，不要 sudo。
Node 版本过低：npm 安装时引擎检查报错。node --version 确认，用 nvm 切到 18+。旧系统自带的 Node（如发行版仓库里长期不更新的版本）建议直接换 nvm。
公司代理环境超时/连不上：设置代理环境变量后再运行：
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
企业自签证书的环境还需要指定 CA：export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem。
npm 镜像源找不到包：部分国内镜像源同步有延迟或不含该包。确认 .npmrc 里的 registry 配置，必要时对这一个包显式使用官方源：npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org。
八、在 Docker 与 CI 中部署
自动化场景（代码评审机器人、批量重构任务、CI 里的 lint-and-fix）是 Claude Code 的强项。一个最小可用的 Dockerfile：
FROM node:22-bookworm-slim
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace
COPY . .
# 非交互模式执行单次任务
CMD ["claude", "-p", "运行测试并总结失败原因"]
运行时注入凭据，绝不写进镜像：
docker run --rm \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-v "$PWD":/workspace \
my-claude-image
CI（GitHub Actions 为例）里同样用 Secret 传递 Key，并给任务设置超时与权限边界。生产环境把 Agent 接进服务器的安全实践——最小权限、审计、回滚边界——我们在此前的 AI Agent 服务器运维一文中有完整讨论。
-p（print 模式）是非交互执行的关键：任务在终端输出结果后退出，适合脚本串联；交互式会话能力（多轮对话、持续上下文）则保留给终端使用场景。
九、装好之后：验证安装的最佳方式
用一个真实的小任务做冒烟测试：进入一个有测试套件的项目，运行 claude，输入"总结这个项目的构建与测试命令，并运行测试"。它应当能读取项目结构、执行命令、给出结果摘要。能走完这个闭环，说明安装、认证、执行权限全部就绪。
后续想深入工作流（自定义 Skills、MCP 扩展、团队共享配置），继续阅读我们的 Claude Code Skills 实战一文。
九、WSL2 环境的完整安装流程
Windows 用户最稳的路径是 WSL2，完整走一遍：
# PowerShell（管理员）：安装 WSL2 与 Ubuntu
wsl --install
# 重启后设置 Linux 用户名与密码，然后进入 WSL
wsl
进入 WSL 后按 Linux 流程操作：安装 nvm 与 Node LTS，再 npm install -g @anthropic-ai/claude-code。几个 Windows 特有的注意事项：
项目文件放 Linux 文件系统里（~/projects 而不是 /mnt/c/...）。跨文件系统 IO 是 WSL2 最大的性能坑，项目放在 /mnt/c 下时 Claude Code 的文件扫描和 git 操作会慢一个数量级。
浏览器回调认证：OAuth 登录需要从 WSL 里打开 Windows 浏览器，WSL2 通常自动处理（WSL interop 会调用默认浏览器）；如果没有自动打开，终端里会打印一个 URL，手动复制到 Windows 浏览器即可。
VS Code 配合：安装 "WSL" 扩展后在 WSL 里 code .，Claude Code 终端与编辑器在同一个 Linux 环境里协作，避免路径映射问题。
十、IDE 集成与项目初始化
VS Code / JetBrains 扩展：Anthropic 提供了 IDE 集成，VS Code 市场搜索 Claude Code 官方扩展安装后，终端里的会话可以感知当前打开的文件与选区（diff 展示也更友好）；JetBrains 系（IntelliJ/WebStorm）有对应插件。CLI 本体仍是前置条件，扩展只是增强了编辑器联动。
项目初始化 /init：第一次在项目里使用时，跑一次 /init 命令，它会让 Claude 分析代码库并生成 CLAUDE.md——记录构建命令、代码规范、架构要点。这份文件是后续所有会话的常驻上下文，值得花几分钟人工修订。团队项目应把 CLAUDE.md 提交进仓库。
配置文件速览：用户级配置在 ~/.claude/settings.json（权限策略、模型偏好等），项目级在 .claude/settings.json 与 .claude/settings.local.json（后者默认不入库）。改动权限前先看官方文档的 settings 说明，不要手改 ~/.claude.json——它是状态文件不是配置文件。
十一、GitHub Actions 中的完整示例
把第二节到第八节的要点收拢成一个可直接抄的 workflow 片段：
name: ai-review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm install -g @anthropic-ai/claude-code
- name: Run Claude Code
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "审查本次 PR 的变更，指出安全问题与遗漏的测试，按严重程度输出列表" \
--output-format text > review.md
- uses: actions/upload-artifact@v4
with:
name: ai-review
path: review.md
要点：timeout-minutes 必须设（Agent 任务可能长跑）；Key 只通过 Secret 注入；任务输出落成 artifact 便于追溯；非交互 -p 模式保证任务结束即退出，不挂流水线。
十二、凭据存储与最小权限
凭据存在哪：订阅登录态保存在操作系统凭据库（macOS 钥匙串 / Windows 凭据管理器 / Linux 的 libsecret），API Key 模式则完全由你自己的环境变量管理。~/.claude.json 里不应有明文 Key，如果发现敏感信息出现在普通文件里，说明配置方式有误，回头检查第四节的两种认证路径。
以最小权限运行：个人开发机上按日常用户运行即可；但在服务器或 CI 里，建议为 Claude Code 创建专用低权限用户，只开放它需要的目录与命令权限。Agent 会真实执行 shell 命令，生产服务器上的权限设计——包括审计与回滚预案——请参考我们此前的 AI Agent 运维安全一文，本文不展开。
十三、认证问题的排查路径
登录环节的故障集中在三类：
登录循环（登录成功又要求登录）：通常是凭据存储环节失败——Linux 服务器没有 keyring 服务时，订阅登录态无法持久化。处理方式是安装 libsecret 相关组件，或改用 API Key 模式绕开 keyring 依赖。远程开发（SSH 到服务器）场景同理：没有桌面环境的机器优先用环境变量方式提供 Key。
凭据过期：订阅登录的 token 会定期刷新，长时间离线的机器再使用时可能要求重新 /login，属正常行为。频繁过期则检查系统时间是否准确——TLS 与 OAuth 对时钟敏感，时钟漂移几分钟就可能造成认证异常。
多账号切换：/login 切换登录身份；API Key 模式下切换组织用不同 Key 的环境变量组合（Key 本身绑定组织与工作区）。团队里"个人订阅干私活、公司 Key 干公活"的场景，建议用 direnv 按目录自动切换 ANTHROPIC_API_KEY，避免误用。
十四、会话数据与磁盘占用管理
Claude Code 的会话记录按项目存放在 ~/.claude/projects/ 下，每个会话一个文件。三个实用点：
恢复现场：claude --resume（或会话内 /resume）可以恢复历史会话继续工作，长任务的上下文不用从头再来；/clear 则清空当前会话上下文重新开始。频繁切换任务的场景，"一个任务一个会话"能显著提升质量——上下文里堆满无关内容是回答质量下降的第一原因。
磁盘占用：重度使用几个月后 ~/.claude/projects/ 可能积累到 GB 级，定期清理旧会话即可；项目级的历史属于工作记录，团队有合规要求时应纳入备份或清理策略统一处理。
升级失败的处理：npm 路径升级报错先试 npm cache clean --force 后重装；原生路径的 claude update 失败多半是安装目录权限或网络问题，重新执行一次安装脚本即可覆盖升级。升级后 claude --version 确认，再用 claude doctor 做一次体检。
十五、装完后的推荐基础配置
五个配置项让日常体验顺滑很多，都在 /config 会话内命令或 settings.json 里完成：
权限模式：日常开发建议保持默认的"写操作需确认"，仅在可信的一次性任务里临时切换；把常用只读命令（git status、ls、测试命令）加入允许清单，减少确认疲劳的同时保住安全边界。
编辑器差异展示：VS Code 用户装官方扩展后，Claude 的文件修改会以 diff 形式在编辑器里展示，接受/拒绝都在编辑器里完成，比终端里翻日志舒服得多。
输出详略：排查 Agent 行为时把输出切到 verbose（或启动时加 -v），平时保持默认——详尽日志会淹没关键信息。
项目级配置入库：团队项目把 .claude/settings.json（权限允许清单、推荐模型）提交进仓库，新成员 clone 即得一致的 Claude Code 行为；个人差异放 settings.local.json。
CLAUDE.md 起步：跑一次 /init 生成初稿后人工修订，把"构建命令、测试命令、目录结构说明、代码禁区"四项写清楚，这四项覆盖了 90% 的日常场景。
十六、安装命令速查表
# ── 安装（二选一）──────────────────────────
npm install -g @anthropic-ai/claude-code # npm 路径，需 Node 18+
curl -fsSL https://claude.ai/install.sh | bash # macOS/Linux 原生路径
# ── 验证与体检 ─────────────────────────────
claude --version
claude doctor
# ── 登录相关 ───────────────────────────────
claude # 项目目录内启动，首次引导登录
# export ANTHROPIC_API_KEY=sk-ant-xxxx # API Key 模式
# ── 维护 ──────────────────────────────────
claude update # 原生路径更新
npm update -g @anthropic-ai/claude-code # npm 路径更新
npm uninstall -g @anthropic-ai/claude-code # npm 路径卸载
rm -rf ~/.claude ~/.claude.json # 彻底清理（会删会话历史）
# ── CI / 自动化 ────────────────────────────
claude -p "任务描述" # 非交互执行，适合脚本与流水线
官方资料与继续阅读
- Anthropic 官方 Claude Code 文档（安装与设置）：https://docs.claude.com/en/docs/claude-code/overview
- npm 包页面（版本与发布记录）：https://www.npmjs.com/package/@anthropic-ai/claude-code
- Node.js 官网（LTS 下载与 nvm 说明）：https://nodejs.org/en/download
- 站内相关文章：Claude Code Skills 实战：用 SKILL.md 打造团队工作流、把 AI Agent 接进服务器运维：权限隔离、审计与回滚边界、Claude Code vs Codex 对比
