EnlightenCode

Claude Code 使用实践：安装、配置与避坑 ​

这篇是我把 Claude Code 真正跑起来后，整理出的一套可复用流程。 不是“命令一贴就完事”，而是从安装、验证、固化配置到避坑都走一遍，确保你能稳定用起来。

先说结论（推荐路径） ​

  • 安装：Node.js LTS + npm install -g @anthropic-ai/claude-code
  • 配置：先用 PowerShell 临时环境变量验证，再决定是否永久化
  • 启动：在项目根目录执行 claude
  • 核验：先过 claude --version，再确认能正常发起会话

0. 前置条件 ​

开始前先确认这些条件：

  • 系统：Windows（示例基于 PowerShell）
  • Node.js：建议 LTS（18+，推荐 20+）
  • npm：可正常使用
  • 你已准备好可用的 API 服务地址与 Token

快速检查：

bash
node -v
npm -v

1. 安装 Claude Code ​

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

如果能看到版本号，CLI 本体就安装成功了。

2. 配置环境变量（核心） ​

最常见、最稳定的配置方式是两个环境变量：

  • ANTHROPIC_BASE_URL
  • ANTHROPIC_AUTH_TOKEN

变量名中的下划线必须写对。 不要在博客、截图、仓库里暴露真实 Token。

2.1 临时配置（建议先做） ​

先在 PowerShell 里跑一遍临时配置，快速判断配置是否正确：

powershell
$env:ANTHROPIC_BASE_URL = "https://api.qinzhiai.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的API密钥"
claude

特点：

  • 仅当前终端会话有效
  • 适合调试和排错
  • 关闭窗口即失效，安全性更高

2.2 永久配置（确认可用后再做） ​

powershell
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.qinzhiai.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的API密钥", "User")

执行后请关闭并重开终端，再运行 claude。

3. 配置文件方案（可选，适合多项目） ​

如果你希望“不同项目用不同节点”，可以改成项目级配置。

在项目根目录创建 .claude/settings.json：

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.qinzhiai.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的APIKey",
    "ANTHROPIC_MODEL": "claude-sonnet-4-5"
  }
}

全局配置路径：

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

4. 建议的实操顺序（少走弯路） ​

  1. 先安装并确认 claude --version
  2. 用临时变量跑通一次 claude
  3. 再决定做永久变量还是项目级配置
  4. 最后再考虑可视化多节点管理工具

这套顺序的核心价值是：每一步都可验证，问题定位非常快。

5. 常见问题排查 ​

5.1 版本正常，但无法启动会话 ​

常见原因：

  • ANTHROPIC_BASE_URL 写错（协议、路径、域名）
  • ANTHROPIC_AUTH_TOKEN 无效或有隐藏空格
  • 你在旧终端里测试，没加载到新变量

快速检查：

powershell
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

5.2 永久变量设置后不生效 ​

  • 重开终端
  • 如果在 IDE 内置终端测试，必要时重启 IDE

5.3 多个项目互相覆盖配置 ​

优先使用项目级 .claude/settings.json，避免全局变量串用。

6. 安全建议（不要跳过） ​

  • 不要把真实 Token 写进文档、截图、录屏
  • 不要提交带凭证的 .claude/settings.json
  • 仓库建议加入忽略规则
gitignore
.claude/settings.json

结语 ​

Claude Code 真正的难点不是安装命令，而是“配置是否可验证、可复现、可维护”。 按“先临时验证 -> 再永久固化 -> 最后按项目管理”这条线走，基本能避开 90% 的坑。