菜单

Claude Code 安装配置指南

发布于 2026年04月04日

1. 环境准备

1.1 Git 安装

  • 下载地址：Git for Windows 官方安装页

  • 作用说明：

    • Claude Code 依赖 Git Bash 运行环境。

    • 缺少 Git 可能导致 Claude Code 启动失败。

  • 安装方式：

    • 下载 Windows 安装包。

    • 大部分选项按默认值安装即可。

1.2 Node.js 安装

  • 下载地址：Node.js 官方中文站

  • 作用说明：

    • Node.js 是 JavaScript 的运行环境。

    • 自带 npm 包管理器。

    • 运行 Node 版 Claude Code 需要它。

  • 安装方式：

    • 下载对应系统安装包。

    • 默认安装即可。

  • 验证命令：

node -v
npm -v

1.3 CC Switch 工具

  • 项目地址：farion1231/cc-switch

  • 工具定位：

    • 可视化管理 API URL 和 Token

    • 支持多站点一键切换

    • 同时兼容 Claude Code、Codex、Gemini CLI

  • 文中提到版本：

    • v3.8.2

    • 发布时间写为 2024 年 12 月

  • 安装方式：

    • 安装版：推荐，支持自动更新

    • 便携版：免安装，但需要手动覆盖更新

2. Claude Code 安装

2.1 安装说明

  • 原文给了 Claude Code 官方文档链接。

2.2 安装方式

方式一：npm 安装

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

  • 原文评价：

    • 稳定

    • 更新方便

    • 更推荐

方式二：独立安装

irm https://claude.ai/install.ps1 | iex

  • 原文说明：

    • 这是官方推荐的独立安装方式

    • 但有用户反馈兼容性问题

3. API / 环境变量配置

  • 原文强调：

    • API 接入 和 官方账号登录 只能二选一

    • 同时配置可能冲突

    • 如果你有官方账号，直接登录即可，不必再配 API 环境变量

3.1 获取 API URL 和 Token

  • 站点：https://www.vmvia.com/

  • 配置流程：

    1. 在站点首页选择线路，取其中一条作为 API URL

    2. 到钱包管理里充值测试

    3. 到令牌管理中新增 Token

  • Token 参数建议：

    • 名称：便于识别

    • 过期时间：个人使用可设为不过期

    • 额度限制：个人使用可设无限额度

    • 缓存时长：

      • 重度开发：1 小时

      • 轻度使用：5 分钟

特别提醒：

  • Claude 启动时会优先检测环境变量

  • 如果没配，可能会直接要求认证

3.3 配置文件方式

  • 配置文件路径：

C:\Users\你的用户名\.claude\config.json

  • 最简示例：

{
  "primaryApiKey": "你的API密钥"
}

  • 如果已有其他配置，就把 primaryApiKey 合并进去。

3.4 CC Switch 图形化配置

  • 这是原文更推荐的方式。

  • 优点：

    • 可视化

    • 方便切换多个 API

    • 配置成本低

  • 操作流程：

    1. 新增配置

    2. 选择供应商

    3. 填写 API Key 与 API URL

    4. 保存并切换到对应配置

  • 字段说明：

    • 供应商名称：自定义标识

    • 官网链接：可选

    • API Key：必填

    • API URL：必填

4. ZCF 快速配置工具

4.1 项目介绍

  • 项目地址：UfoMiao/zcf

  • 功能定位：

    • 自动安装和配置 Claude Code

    • 预配常用 MCP 服务器

    • 集成提示词模板

    • 一键完成初始化

4.2 快速安装

npx zcf

  • 前提：已安装 Node.js

4.3 推荐配置流程

  • 安装类型：完整安装

  • API 配置：自行配置，搭配 CC Switch

  • MCP 服务器：原文推荐安装

    • context7

    • deepwiki

    • 其他按需

  • 完成安装后：

    • 关闭终端

    • 重新打开

4.4 启动测试

claude

5. CCometixLine 状态栏配置

5.1 插件简介

  • 项目地址：Haleclipse/CCometixLine

  • 主要作用：

    • 显示当前模型

    • 显示令牌消耗

5.2 安装命令

npm install -g @cometix/ccline

5.3 配置方法

  • 配置文件：

    • Windows：C:\Users\你的用户名\.claude\settings.json

    • Linux/macOS：~/.claude/settings.json

  • Windows 示例：

{
  "statusLine": {
    "type": "command",
    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
    "padding": 0
  }
}

  • Linux/macOS 示例：

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/ccline/ccline",
    "padding": 0
  }
}

  • npm 方式的 fallback 示例：

{
  "statusLine": {
    "type": "command",
    "command": "ccline",
    "padding": 0
  }
}

5.4 CC Switch 用户额外配置

  • 建议在 CC Switch 的“通用配置”里加入状态栏配置。

图7：CC Switch 中加入状态栏配置
{
  "includeCoAuthoredBy": false,
  "statusLine": {
    "type": "command",
    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
    "padding": 0
  }
}

6. Claudia Global 可视化工具

6.1 工具介绍

  • 项目地址：who10086/claudia-global

  • 功能：

    • 可视化查看历史记录

    • 管理 API 和 URL

    • 可作为 CC Switch 的替代方案

7. 常见问题排查

7.1 找不到 claude 命令

  • 常见报错：

    • 系统找不到 claude

  • 排查步骤：

    1. 先用 where claude 找安装路径

    2. Windows 常见 npm 全局目录是：

C:\Users\你的用户名\AppData\Roaming\npm

  1. 把这个目录加入 Path

  2. 重启终端

  3. 再执行：

claude --version

8. 常见错误处理

8.1 API 相关错误

429

  • 含义：请求过快或触发限流

  • 处理思路：

    • 等 1 到 5 分钟

    • 降低请求频率

    • 联系站点提高额度

    • 用 CC Switch 切换备用站点

401

  • 含义：Token 无效、过期或填写错误

  • 处理思路：

    • 检查 Token 是否完整

    • 重新生成 Token

    • 检查环境变量和配置文件

    • 清理 .claude 下缓存

403

  • 含义：访问被拒绝

  • 原文给的常见原因：

    • 余额不足

    • 账号被封

    • IP 受限

  • 处理思路：

    • 检查余额

    • 更换网络或代理

    • 联系站点客服

500

  • 含义：站点服务端异常

  • 处理思路：

    • 等待恢复

    • 切备用线路

    • 切备用站点

Timeout

  • 含义：连接超时

  • 处理思路：

    • 检查网络

    • 切换网络

    • 调整超时参数

8.2 配置相关错误

找不到配置文件

  • 可手动创建：

# Windows
mkdir %USERPROFILE%\.claude
echo {} > %USERPROFILE%\.claude\config.json

# Linux/macOS
mkdir -p ~/.claude
echo '{}' > ~/.claude/config.json

配置文件 JSON 格式错误

  • 检查点：

    • 逗号是否多余

    • 引号是否正确

    • JSON 是否合法

  • 原文给了一个正确示例：

{
  "primaryApiKey": "sk-xxxxx",
  "statusLine": {
    "type": "command",
    "command": "ccline"
  }
}

8.3 运行时错误

Git 未安装

  • 处理方式：回到 1.1 节安装 Git

Node.js 版本过低

  • 原文要求：>= 18.0.0

  • 处理方式：

    • 卸载旧版本

    • 安装新版本

    • 用 node -v 验证

权限不足

  • Windows：

    • 用管理员身份运行 PowerShell / CMD

  • Linux/macOS：

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

8.4 MCP 相关错误

MCP 服务器无法连接

  • 排查项：

    • 服务器地址是否正确

    • 配置是否正确

    • 防火墙是否拦截

MCP 工具调用失败

  • 排查项：

    • 查看 MCP 服务日志

    • 检查参数格式

    • 重启 MCP 服务

8.5 快速诊断流程

API错误

  • 用 CC Switch 统一切换

  • 避免单点故障

  • 小额多次充值以降低风险


评论