Claude Code npm 客户端使用指南
Claude Code 是 Anthropic 官方推出的 AI 编程助手终端工具，可直接在终端中理解代码库、编辑文件、执行命令，并通过自然语言驱动整个开发工作流。
一、环境要求
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.0.0 | 22.x LTS |
| npm | 9.0 | 10.x |
| Git | 2.38+ | 2.47+ |
| 操作系统 | macOS 13+ / Ubuntu 20.04+ / WSL2 | macOS 15 / Ubuntu 24.04 |
- 内存：最低 4 GB，推荐 16 GB+
- 磁盘空间：约 150 MB
二、安装
2.1 通过 npm 全局安装（推荐）
npm install -g @anthropic-ai/claude-code
⚠️ 不要使用
sudo npm install -g，这会导致权限问题。
2.2 验证安装
claude --version
如果遇到 command not found，请配置 npm 全局路径：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
将上述 export 行添加到 ~/.bashrc、~/.zshrc 或 ~/.bash_profile 中以持久生效。
2.3 其他安装方式
| 方式 | 命令 |
|---|---|
| npx 免安装运行 | npx @anthropic-ai/claude-code |
| 项目本地安装 | npm install --save-dev @anthropic-ai/claude-code |
| 更新版本 | npm update -g @anthropic-ai/claude-code |
2.4 使用原生安装器（2026 年推荐）
Anthropic 现在推荐大多数用户使用原生安装器（无需 Node.js 依赖，支持后台自动更新）：
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# macOS via Homebrew
brew install --cask claude-code
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows WinGet
winget install Anthropic.ClaudeCode
npm 方式仍完全受支持，适用于 CI/CD 管道、Docker 环境、monorepo 管理等场景。
三、首次启动与认证
claude
首次启动时：
- 终端会显示一个 OAuth URL
- 浏览器自动打开要求登录 Anthropic 账号
- 需要 Claude Pro、Max、Teams 或 Enterprise 订阅（免费账号不可用）
或使用 API Key 方式：
export ANTHROPIC_API_KEY="sk-ant-你的key"
claude
四、命令行选项
4.1 基础使用
| 命令 | 说明 |
|---|---|
claude |
启动交互式 REPL 会话 |
claude "写一个排序函数" |
以初始 prompt 启动 REPL |
claude -p "解释这段代码" |
一次性打印模式（非交互） |
cat file.ts | claude -p "找bug" |
通过管道传入内容 |
claude -v / --version |
查看版本号 |
claude -h / --help |
查看帮助 |
claude update |
更新到最新版本 |
4.2 会话管理
| 命令 | 说明 |
|---|---|
claude -c / --continue |
继续上次的会话 |
claude -c -p "继续修改" |
继续会话 + 运行 prompt |
claude -r <id> / --resume <id> |
按 ID 恢复会话 |
claude --resume <名称> |
按保存名称恢复会话 |
claude --fork-session |
创建新会话 ID（而非复用原 ID） |
claude --from-pr <PR> |
恢复与某个 GitHub PR 关联的会话 |
4.3 配置管理
| 命令 | 说明 |
|---|---|
claude config |
交互式配置向导 |
claude config list |
列出所有配置项 |
claude config get <key> |
获取某个配置值 |
claude config set <key> <val> |
设置某个配置值 |
claude config add <key> <vals...> |
向数组配置追加值 |
claude config remove <key> <vals...> |
从数组配置移除值 |
4.4 重要 CLI 标志
| 标志 | 说明 |
|---|---|
--model <名称> |
指定模型（如 claude-sonnet-4-6、claude-opus-4-8） |
--output-format <text|json|stream-json> |
输出格式 |
--input-format <text|stream-json> |
输入格式 |
--max-turns <N> |
限制最大工具调用轮数 |
--max-budget-usd <金额> |
限制最大 API 花费（美元） |
--system-prompt "<prompt>" |
替换默认系统提示词 |
--append-system-prompt "<prompt>" |
追加到默认系统提示词 |
--allowedTools <列表> |
白名单工具（如 Bash,Read,Edit） |
--disallowedTools <列表> |
黑名单工具 |
--dangerously-skip-permissions |
⚠️ 跳过所有权限确认（仅 CI 场景使用） |
--remote "<任务描述>" |
在 claude.ai 上创建 Web 会话 |
--teleport |
在本地终端恢复 Web 会话 |
--debug "api,mcp" |
调试特定类别 |
--add-dir <目录> |
添加额外的工作目录 |
--json-schema '<schema>' |
获取校验后的 JSON 输出（打印模式） |
--verbose |
启用详细日志输出 |
4.5 常用组合示例
# 在项目目录中启动交互式会话
cd my-project && claude
# 非交互式快速查询
claude -p "分析这个项目的目录结构"
# 继续上次的会话
claude --continue
# 指定模型
claude --model claude-opus-4-8
# JSON 格式输出（适合自动化）
claude -p "列出所有函数" --output-format json
# 管道模式 — 从文件查找错误
cat logs.txt | claude -p "找出其中的错误并给出修复建议"
# CI/CD 场景：限制预算并跳过确认
claude -p --max-budget-usd 5.00 --dangerously-skip-permissions \
"运行测试并报告结果"
五、交互式 Slash 命令
在 REPL 会话内部，输入 / 可看到所有命令：
| 命令 | 用途 |
|---|---|
/help |
显示帮助信息 |
/exit |
退出会话 |
/clear |
清空当前对话上下文 |
/compact |
压缩上下文（减少 token 占用） |
/compact [指令] |
按指定焦点压缩 |
/init |
生成项目 CLAUDE.md 配置文件 |
/config |
打开配置菜单 |
/cost |
查看当前会话 token 用量和费用 |
/doctor |
环境健康检查 |
/model |
切换模型 |
/agents |
管理子 Agent |
/mcp |
管理 MCP 服务器 |
/memory |
编辑记忆（持久化事实与偏好） |
/login / /logout |
切换账号认证 |
/review |
请求代码审查 |
/commit |
生成 Git 提交信息 |
/sessions |
列出历史会话 |
/status |
查看系统和账户状态 |
/bug |
向 Anthropic 报告 Bug |
/permissions |
管理工具权限设置 |
/skills |
列出可用的技能（Skills） |
/plugins |
管理插件 |
/bashes |
列出后台运行中的进程 |
/kill <id> |
停止指定后台进程 |
/fast |
切换快速模式（Opus 快速输出） |
/search |
搜索项目代码 |
/loop |
设置定时重复任务（如 /loop 5m /status） |
六、配置文件层级
Claude Code 的配置按优先级从低到高分为四层：
| 层级 | 文件路径 | 用途 |
|---|---|---|
| 全局用户配置 | ~/.claude/settings.json |
个人偏好（可提交） |
| 全局私有配置 | ~/.claude/settings.local.json |
敏感信息（token 等） |
| 项目共享配置 | .claude/settings.json |
团队配置（应纳入 Git） |
| 项目私有配置 | .claude/settings.local.json |
项目级个人覆盖 |
此外，项目根目录的 CLAUDE.md 用于向 Claude Code 描述项目结构、编码规范和技术栈，可通过 /init 命令自动生成。
七、从 npm 迁移到原生版本
如果先通过 npm 安装，后来想切换到原生安装器：
claude install
该命令会自动：
- 下载并安装原生版本
- 保留所有已有配置
- 移除 npm 版本
八、卸载
# 卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code
# 卸载原生版本（macOS/Linux）
rm -rf ~/.local/share/claude-code
参考资料
- Claude Code 官方文档
- GitHub: anthropics/claude-code
- Claude Code 第一天使用指南
- Installation and First Launch - Tutorial
📝 提示：本文档覆盖了 2026 年 6 月 Claude Code 的最新功能，部分命令可能随版本更新而变化。运行
claude -h获取本地安装版本的最新帮助信息。
💬 评论