Claude Code 安装踩坑实录

晨曦蜗牛

614人浏览 · 2026-04-01 11:33:25

晨曦蜗牛 · 2026-04-01 11:33:25 发布

文章目录

Claude Code 安装踩坑实录

Claude Code 安装踩坑实录

记录在 Windows 上安装 Claude Code 的完整过程，包括走过的弯路和最终的解决方案。供后来者参考，避免重复踩坑。

一、winget 安装：此路不通

第一反应是用 Windows 自带的包管理器 winget 安装，连续尝试了 7 次：

C:\Users\CXWN>winget install ClaudeCode
找不到与输入条件匹配的程序包。

结论：Claude Code 不在 winget 仓库中，无法通过 winget install 安装。不要在这条路上浪费时间。

二、npm 安装：小心仿冒包

放弃 winget 后转向 npm，直觉性地执行了：

npm install -g claude-code

安装成功了，但运行时提示：

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Wrong package!                                             │
│                                                             │
│  Please install the correct package:                        │
│                                                             │
│    npm install -g @anthropic-ai/claude-code                 │
│                                                             │
│  Official package:                                          │
│  https://www.npmjs.com/package/@anthropic-ai/claude-code   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

npm 上存在一个非官方仿冒包 claude-code，安装后命令是 claude-code，运行就会提示 “Wrong package!”。

正确做法：先卸载仿冒包，再装官方包：

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

注意：正确的包名是 @anthropic-ai/claude-code（带 @anthropic-ai/ 前缀），安装后的命令是 claude（不是 claude-code）。

安装完成后验证：

C:\Users\CXWN>claude --version
2.1.74 (Claude Code)

三、首次启动：模型访问错误

安装成功后，在项目目录中启动 Claude Code：

G:\workspace\git\temp\case-01>claude

界面正常显示了欢迎画面（显示 Opus 4.6 · API Usage Billing），但输入任何内容都报错：

● There's an issue with the selected model (claude-opus-4-6).
  It may not exist or you may not have access to it.
  Run /model to pick a different model.

尝试用 /model 切换模型（包括 opus、sonnet、Default），每个都报同样的错误。甚至出现了带 [1m] ANSI 转义码的异常模型 ID：

Set model to opus[1m] (claude-opus-4-6[1m])

原因分析：API Key 对应的账户暂时无法访问所选模型，可能是权限问题或网络波动。

解决：多次重试后恢复正常，能够正常对话：

❯ 你是谁啊

● 我是 Claude Code，Anthropic 的官方命令行工具。我使用的模型是 Claude Opus 4.6。

这类模型访问错误通常是临时性的，重新启动 Claude Code 或等待片刻后重试即可。

四、诊断工具：claude doctor

遇到问题时可以运行 claude doctor 进行健康检查：

G:\workspace\git\temp\case-01>claude doctor

  Diagnostics
  └ Currently running: npm-global (2.1.74)
  └ Path: D:\Toolkit\Nodejs\node.exe
  └ Invoked: C:\Users\CXWN\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\cli.js
  └ Config install method: unknown
  └ Search: OK (vendor)
  Updates
  └ Auto-updates: enabled
  └ Update permissions: Yes
  └ Auto-update channel: latest
  └ Stable version: 2.1.58
  └ Latest version: 2.1.74

从诊断信息可以看到：

安装方式为 npm 全局安装（npm-global）
Node.js 路径为 D:\Toolkit\Nodejs\node.exe
Claude Code 的实际位置在 C:\Users\CXWN\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\cli.js
自动更新已启用
当前版本已是最新（2.1.74）

五、配置探索

成功运行后，开始探索 Claude Code 的配置体系。

5.1 查看配置的方式

交互模式中输入 /config 打开配置界面
CLI 中运行 claude config list 查看配置（注意：该命令在某些版本中可能返回错误）
直接查看配置文件：%USERPROFILE%\.claude\settings.json

5.2 通过 /config 完成的设置

❯ /config
  ⎿  Set response language to 简体中文
     Enabled auto-connect to IDE

设置了两项：

响应语言 → 简体中文
自动连接 IDE → 已启用

5.3 配置文件体系

文件	路径	说明
全局设置	`~/.claude/settings.json`	所有项目生效
项目设置	`.claude/settings.json`	仅当前项目，优先级更高
全局 MCP	`~/.claude/mcp.json`	全局 MCP 服务器配置
项目 MCP	`.claude/mcp.json`	项目级 MCP 服务器配置

5.4 settings.json 配置结构

{
  "model": "opus",                    // 默认模型 (opus / sonnet / haiku)
  "language": "简体中文",              // 响应语言
  "env": {                            // 环境变量
    "ANTHROPIC_API_KEY": "...",       // API 密钥
    "ANTHROPIC_BASE_URL": "...",      // 自定义 API 地址
    "ANTHROPIC_MODEL": "...",         // 模型 ID
    "API_TIMEOUT_MS": "300000",       // API 超时（毫秒）
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", // 禁用遥测
    "CLAUDE_CODE_LOG_LEVEL": "debug"  // 日志级别
  },
  "permissions": {},                  // 权限规则
  "hooks": {}                         // 钩子配置
}

5.5 CLI 启动参数速查

核心参数

参数	说明
`-p, --print`	非交互模式，输出后退出（适合管道）
`-c, --continue`	继续最近一次对话
`-r, --resume [id]`	通过 session ID 恢复对话
`--model <model>`	指定模型（如 opus、sonnet）
`--effort <level>`	推理深度：low / medium / high / max

权限控制

参数	说明
`--permission-mode <mode>`	权限模式：default / acceptEdits / plan / dontAsk / auto / bypassPermissions
`--allowed-tools <tools>`	允许的工具（如 `"Bash(git:*) Edit"`）
`--disallowed-tools <tools>`	禁止的工具

系统提示 & 输入输出

参数	说明
`--system-prompt <prompt>`	自定义系统提示
`--append-system-prompt <prompt>`	追加系统提示
`--output-format <format>`	输出格式：text / json / stream-json

会话管理

参数	说明
`--session-id <uuid>`	指定会话 ID
`--fork-session`	恢复时创建新会话分支
`--no-session-persistence`	禁用会话持久化

工具 & 扩展

参数	说明
`--tools <tools>`	指定可用工具（`""` 禁用全部）
`--mcp-config <configs>`	加载 MCP 服务器配置文件
`--plugin-dir <paths>`	加载插件目录

Agent & 工作区

参数	说明
`--agent <agent>`	指定 agent
`-w, --worktree [name]`	创建 git worktree 隔离工作区
`--add-dir <dirs>`	添加额外的可访问目录

调试 & 其他

参数	说明
`-d, --debug [filter]`	调试模式（如 `"api,hooks"`）
`--verbose`	详细模式
`--max-budget-usd <amount>`	API 消费上限（美元，仅 `--print`）
`--fallback-model <model>`	主模型过载时的备用模型
`--ide`	自动连接 IDE

5.6 子命令

命令	说明
`claude auth`	管理认证
`claude mcp`	管理 MCP 服务器
`claude agents`	列出已配置的 agents
`claude plugin`	管理插件
`claude doctor`	健康检查
`claude update`	检查并安装更新
`claude install [target]`	安装指定版本
`claude setup-token`	配置长期认证令牌

5.7 交互模式斜杠命令

命令	说明
`/config`	打开配置界面
`/model`	切换模型
`/help`	帮助
`/clear`	清除上下文
`/compact`	压缩对话
`/cost`	查看当前会话花费
`/fast`	切换快速模式

六、经验总结

踩坑点	教训
winget 安装	Claude Code 不在 winget 仓库，别浪费时间
npm 仿冒包	正确包名是 `@anthropic-ai/claude-code`，不是 `claude-code`
命令名	安装后命令是 `claude`，不是 `claude-code`
模型错误	“There’s an issue with the selected model” 通常是临时问题，重试即可
诊断工具	遇到问题先跑 `claude doctor`
配置文件	全局配置在 `%USERPROFILE%\.claude\settings.json`