← 返回 Blog
UseAIAPIAI API4min

Windows/Mac/Linux 全覆盖：Claude Code 安装配置从零到第一句 Hello World，踩坑清单我都帮你列好了

想要在本地设备运行 Claude Code，从环境部署到调试出首个 Hello World 程序，核心只需搞定三项工作：完善 Node.js 运行环境、优化软件安装源、配置合规 API 接入信息。做好以上三点，即可在全系统环境平稳启用 Claude Code。

ClaudeClaude CodeClaude Code 全平台部署实操指南

Claude Code 全平台部署实操指南：Windows/macOS/Linux 三步完成环境与 API 配置

想要在本地设备运行 Claude Code，从环境部署到调试出首个 Hello World 程序，核心只需搞定三项工作：完善 Node.js 运行环境、优化软件安装源、配置合规 API 接入信息。做好以上三点，即可在全系统环境平稳启用 Claude Code。

一、部署前置硬件与软件要求

当前 Anthropic 官方优先推荐 Homebrew、系统脚本、WinGet 原生安装方案，不再建议新手采用 npm 安装。一方面 npm 开源生态存在恶意依赖包隐患，另一方面极易引发 Node 版本权限冲突。

表格

配置项最低标准推荐配置
操作系统Win10/Win11（64 位）、macOS 全版本、Linux（含 WSL 子系统）主流稳定系统正式版
Node.jsv18 及以上v24 LTS 长期支持版
运行内存4GB8GB 及以上
网络条件可正常连通 Anthropic 官方服务或合规 API 中转节点低延迟稳定链路

二、Windows 系统分步安装教程

Step1 安装并校验 Node.js

前往 Node.js 官网https://nodejs.org下载 MSI 安装包，安装过程务必勾选Add to PATH选项，规避后续指令无法识别问题。

安装完成后，以管理员身份启动 PowerShell 或终端，执行校验命令：

bash

运行

node --version

输出版本号≥v20.x.x 即代表安装成功。

Step2 安装 Git 运行环境

Windows 端 Claude Code 依托 Git Bash 实现脚本运行，缺失 Git 会导致程序缺少执行载体，使用系统包管理器安装：

bash

运行

winget install Git.Git

默认安装路径：C:\Program Files\Git\bin\bash.exe，妥善留存路径信息。

Step3 配置系统环境变量

按下Win+R输入sysdm.cpl打开系统属性→高级→环境变量，在用户变量中新建配置：

表格

变量名称变量取值
CLAUDE_CODE_GIT_BASH_PATHC:\Program Files\Git\bin\bash.exe

Step4 两种安装方式任选其一

方案 A：WinGet 官方安装（首选）

bash

运行

winget install Anthropic.ClaudeCode

链路异常时切换备选 npm 安装方案。

方案 B：npm 搭配国内镜像源（备选）

bash

运行

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

安装完毕校验程序：

bash

运行

claude --version

若提示指令不存在，将C:\Users\用户名\.local\bin添加至系统 Path 环境变量，重启终端生效。

Step5 调整 PowerShell 脚本权限

初次运行大概率触发脚本拦截报错，管理员终端执行权限放行指令：

bash

运行

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

三、macOS（Intel/M 系列芯片通用）安装步骤

方式一：Homebrew 一键部署（官方推荐）

bash

运行

# 未安装Homebrew先执行安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装Claude Code客户端
brew install --cask claude-code
# 版本校验
claude --version

方式二：GUI 可视化安装

前往 Claude 官方渠道下载 dmg 安装包，拖拽至应用程序文件夹完成安装。

可选：Nvm 管控 Node 版本，规避系统环境冲突

bash

运行

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/latest/install.sh | bash
nvm install 20
nvm use 20

四、Linux 与 WSL 子系统部署方案

原生 Linux（Ubuntu/Debian/CentOS/Arch）

优先配置 Node 环境后通过 npm 安装：

bash

运行

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

WSL Ubuntu 专项配置

bash

运行

# 更新系统Node至20.x稳定版
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 全局安装Claude Code
sudo npm install -g @anthropic-ai/claude-code
claude --version

五、国内环境核心配置：API 中转参数设置

本地部署完成后直接访问官方接口极易链路超时，通过配置 BaseURL 与密钥，将请求路由至合规接入节点是国内环境落地关键。

方案一：配置文件持久化（推荐，一次配置长期生效）

表格

系统配置文件路径
macOS/Linux~/.claude/settings.json
WindowsC:\Users\ 用户名.claude\settings.json

配置文件参考模板：

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-你的密钥内容",
    "ANTHROPIC_BASE_URL": "https://api.中转域名.com/v1",
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "API_TIMEOUT_MS": "300000"
  }
}

注：错误字段ANTHROPIC_SASE-URL、ANTHROPIC_SUTH_TOKEN不可使用，系统仅识别ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY；BaseURL 结尾必须携带/v1，不能填写官网登录页地址。

若启动仍弹出登录引导，同目录新建.claude.json跳过初始化引导：

json

{
  "hasCompletedOnboarding": true
}

方案二：终端临时环境变量（调试测试用）

macOS/Linux

bash

运行

export ANTHROPIC_BASE_URL="https://api.xxx.com/v1"
export ANTHROPIC_API_KEY="sk-ant-..."
claude

Windows PowerShell

powershell

$env:ANTHROPIC_BASE_URL="https://api.xxx.com/v1"
$env:ANTHROPIC_API_KEY="sk-ant-..."
claude

调试连通后，建议迁移至配置文件固化参数。

六、初始化调试，运行首个 Hello World 示例

切换至本地项目目录，启动交互终端：

bash

运行

cd ~/项目文件夹
claude

跟随引导默认回车完成初始化配置，进入对话界面后输入指令：

plaintext

Write a Python function to determine if a number is prime

成功生成代码即部署完成。

随时执行环境体检：

bash

运行

claude doctor

七、高频踩坑汇总与解决方案

表格

故障现象处理办法
误用网页面板地址作为 BaseURL，接口返回 404规范格式：https://api.xxx.com/v1
Windows 安装后 claude 指令无法识别将.local\bin写入系统 Path，重启终端
PowerShell 禁止脚本运行执行前文 RemoteSigned 权限配置指令
WSL 与 Windows 配置文件混用异常在 WSL 内部路径独立配置 settings.json
初始化强制跳转登录页填入正确 API 密钥与 BaseURL，新增 hasCompletedOnboarding 配置

八、日常常用指令汇总

表格

使用场景执行命令
开启交互对话claude
单次指令执行claude "Fix build errors"
清空当前对话上下文/clear
环境自检排错claude doctor
切换推理模型/model claude-sonnet-4-5
客户端版本更新claude update

对于需要批量开发、高频调用 Claude、Gemini、DeepSeek 等主流大模型的个人开发者与企业团队，可依托专业 API 一站式服务简化部署流程。UseAIAPI 汇聚多款全球主流大模型接入能力，省去繁琐的多模型环境适配与接口调试步骤。

在定价层面，平台官方原价五折的专属优惠能够显著压缩高强度代码生成、批量推理场景的使用开销；面向企业用户还可提供定制化专属部署方案，包含专属链路部署、标准化 SLA 服务协议、7×24 小时全天候运维支持，适配生产环境长期稳定调用需求。