从零开始 · 第一篇
在 Windows 上安装
Claude Code
从打开第一个窗口,到让 AI 写出第一个文件。
照着 8 步做,把 Claude Code 接入你的 SHUN API。
核对日期: · 预留约 30–60 分钟,下载时间取决于网络。
开始前,准备好这些
顺序:Node.js(自带 npm)→ Git → 用 npm 安装 Claude Code → 接入 SHUN API。全程使用 Windows 自带的 PowerShell,最后让 Claude Code 在练习目录中写文件。
电脑:Windows 10(1809+)或 Windows 11,x64 / ARM64,至少 4 GB 内存。按 Win + R 输入 winver 查版本;「设置 → 系统 → 关于」查架构和内存。[1]
用户 key 由 SHUN 管理员提供,相当于接入密码。安装成功不代表模型已开通;第 8 步实际调用会消耗账号额度。
Node.js、Git 和 SHUN 登录图为真实页面截图,橙色标记指出操作位置;PowerShell 图为示意。图片可点击放大。
打开 PowerShell
按 Win 键,搜索 PowerShell,点「Windows PowerShell」的「打开」。普通打开即可,不选 ISE。
PS C:\Users\…>,就找对窗口了。标有 PowerShell 的命令粘贴到这里。先安装 Node.js,带上 npm
① 下载 Windows 安装包
- 打开 Node.js 官方下载页。顶部 ① 版本选 Node.js 24 LTS(长期支持版);Claude Code 的 npm 包要求 Node.js 22 或更新版本。[1][3]
- 向下越过 Docker 命令框,在 Or get a prebuilt Node.js® for 一行:② 系统选 Windows;③ 架构按系统类型选 x64(普通 Intel / AMD)或 ARM64。
- 点击 ④ Windows Installer(.msi) 绿色按钮,下载后双击安装。此处不用 Docker 命令或
.zip。
② 安装时保留 npm 和 PATH
- 阅读并接受许可,安装位置保持默认,点 Next。
- Custom Setup 保留 npm package manager 和 Add to PATH,让终端能找到程序。
- Tools for Native Modules 额外工具无需勾选。点 Install,确认 Windows 提示中的官网安装程序,完成后点 Finish。
③ 重开终端检查
关闭全部终端,从开始菜单重开 PowerShell,逐行运行:
node --version
npm.cmd --version例如 v24.x.x 和 11.x.x;Node.js 主版本至少为 22。npm 随 Node.js 安装,不用另下。[9]
为什么命令带 .cmd?
npm.cmd、claude.cmd 是 Windows 命令启动器,可避开 PowerShell 优先运行 .ps1 时的脚本策略报错,无需更改执行策略。[6]
再安装 Git for Windows
Git 提供 Claude Code 可用的 Git Bash 命令环境。本篇先装好它,无需 GitHub 账号或 SSH 密钥。[1]
① 下载对应架构的 Setup
- 打开 Git 官方 Windows 下载页,找到 Other Git for Windows downloads → Standalone Installer。
- 普通 Intel / AMD 电脑选 ① Git for Windows/x64 Setup;ARM 电脑选 ② ARM64 Setup。下载
.exe,不用下方 Portable。
② 安装并检查
- 双击安装包,阅读许可,目录和组件保持默认。
- 在 Adjusting your PATH environment 页选 Git from the command line and also from 3rd-party software。[6]
- 其余默认,依次点 Next → Install → Finish。关闭全部终端,重开 PowerShell:
git --versiongit version … 后,再从开始菜单打开一次 Git Bash。能打开命令窗口即可关闭;下面仍在 PowerShell 操作。
用 npm 安装 Claude Code
在 PowerShell 完整复制这一行并回车。-g 安装到 npm 全局目录,@latest 获取当时最新版。[1]
npm.cmd install -g @anthropic-ai/claude-code@latest等待重新出现 PS C:\…>。有 npm error 先查排错表;仅提示 npm 可更新无需处理。然后关闭全部终端,重开 PowerShell:
claude.cmd --version已经装过原生版 / WinGet 版?
用 Get-Command claude -All 核对位置。已有版本正常可用时直接做第 5 步,后文 claude.cmd 改用 claude,并沿用原方式更新。需要更换安装方式时按官方卸载说明操作,保留个人配置和会话。
拿到用户 key 和可用的 Claude 模型
- 向管理员领取个人用户 key,确认账号已开通支持 Claude Code 的 Claude 模型。
- 打开 SHUN API 控制台,用用户 key 登录,确认额度可用。
- 复制管理员确认可用的完整模型 ID,保留所有连字符和后缀,不能只填「Claude」或「Sonnet」。
价格表有某型号不代表你的账号已开通。模型列表为空、无 Claude 或报 503 时,联系管理员确认渠道、权限和额度;可以安装软件,但第 8 步暂时无法完成。
本篇使用 SHUN 网关凭据,不需要管理员密钥或 Claude Pro / Max 订阅。不要把用户 key 发给模型、截图或公开代码。[4]
把 Claude Code 接到 SHUN API
在你电脑的 PowerShell 一次复制整段,回车后按提示依次粘贴 key、模型 ID,各按一次回车。key 输入显示星号或不显示字符均正常。
https://apivip.shun.team。Claude Code 自己添加 /v1/messages,这里不要再加 /v1。
& {
$ErrorActionPreference = 'Stop'
$shunSecret = Read-Host '粘贴你的 SHUN 用户 key,然后回车' -AsSecureString
try {
$shunToken = [Net.NetworkCredential]::new('', $shunSecret).Password.Trim()
$shunModel = (Read-Host '粘贴可用的完整 Claude 模型 ID,然后回车').Trim()
if (!$shunToken -or $shunToken -match '\s') { throw 'key 为空或含空格,请重新复制' }
if (!$shunModel -or $shunModel -match '\s') { throw '模型 ID 为空或含空格,请从可用列表完整复制' }
$shunSettings = @{
ANTHROPIC_BASE_URL = 'https://apivip.shun.team'
ANTHROPIC_AUTH_TOKEN = $shunToken
ANTHROPIC_MODEL = $shunModel
ANTHROPIC_DEFAULT_HAIKU_MODEL = $shunModel
ANTHROPIC_DEFAULT_SONNET_MODEL = $shunModel
ANTHROPIC_DEFAULT_OPUS_MODEL = $shunModel
ANTHROPIC_DEFAULT_FABLE_MODEL = $shunModel
}
foreach ($shunName in $shunSettings.Keys) {
[Environment]::SetEnvironmentVariable($shunName, $shunSettings[$shunName], 'User')
[Environment]::SetEnvironmentVariable($shunName, $shunSettings[$shunName], 'Process')
}
Write-Host 'SHUN 配置已保存。继续下面的检查;不要把 key 粘贴到聊天框。'
} finally {
$shunSecret.Dispose()
$shunToken = $null
$shunSettings = $null
}
}命令保存到当前 Windows 用户,并立即用于本窗口;主会话和模型别名统一使用你输入的型号。key 保存为普通环境变量,不是加密保险箱;已有其他服务配置时先请管理员核对,避免覆盖。[5][8]
在同一个 PowerShell 检查
& {
Write-Host ('地址:' + $env:ANTHROPIC_BASE_URL)
Write-Host ('模型:' + $env:ANTHROPIC_MODEL)
Write-Host ('用户 key 已配置:' + [bool]$env:ANTHROPIC_AUTH_TOKEN)
}True。这只检查本机配置;是否能调用仍要看第 8 步。
建一个练习文件夹,第一次启动
在刚完成配置的 PowerShell 运行,程序会自动使用你的 Windows 用户目录:
& {
$ErrorActionPreference = 'Stop'
$shunPractice = Join-Path $env:USERPROFILE 'Claude-Learning'
New-Item -ItemType Directory -Path $shunPractice -Force | Out-Null
Set-Location -LiteralPath $shunPractice
claude.cmd
}创建或进入目录失败时会停止。命令不删除已有文件;若 Claude-Learning 已有重要资料,另建空目录练习。
- 首次选择主题时用 ↑ / ↓,按 Enter 确认;阅读 Security notes 后回车继续。
- 出现 Accessing workspace,确认路径是自己的
Claude-Learning,用方向键选 Yes, I trust this folder 并回车(默认可能是退出)。 - 进入 Claude Code 输入区后,粘贴下方命令并回车:
/statusAnthropic base URL 应是 https://apivip.shun.team,Auth token 来源应是 ANTHROPIC_AUTH_TOKEN,Model 应是选定的完整 ID。按 Esc 返回输入区。[4]
退出后回到刚配置的 PowerShell,复查第 6 步并重新启动;正常读取网关 token 后应跳过官网登录。已有设置或组织登录策略可能冲突,请管理员核对,不要修改内部标记跳过向导。
让它写一个文件,完成第一次使用
把下面这句话粘贴到 Claude Code 输入区并回车;这一步会调用模型并消耗额度。
请在当前文件夹创建一个 UTF-8 文本文件 hello.txt,内容是“你好,Claude Code!这是我的第一次练习。”。如果文件已存在,请先询问我,不要覆盖。只做这一件事,完成后告诉我文件在哪里。出现 Create file 时,确认目标为练习目录的 hello.txt、内容正确,选 1. Yes(仅允许本次操作)并回车;无关操作先拒绝。
打开文件,检查结果
按 Win + E 打开资源管理器,在顶部地址栏粘贴:
%USERPROFILE%\Claude-Learning双击 hello.txt(隐藏扩展名时显示 hello),用记事本查看中文内容。
只有“已完成”的回复不够。没有文件时继续要求它实际写入;报错则按下表处理。可到 SHUN「使用记录」核对调用。
下次使用
在 Claude Code 输入 /exit 退出。下次重开 PowerShell,回到练习目录启动:
& {
$ErrorActionPreference = 'Stop'
Set-Location -LiteralPath (Join-Path $env:USERPROFILE 'Claude-Learning')
claude.cmd
}目录不存在会停止启动。/help 查看帮助,/resume 继续旧对话;更新 npm 版时先退出 Claude Code,再运行:[2]
npm.cmd install -g @anthropic-ai/claude-code@latest换 key 或模型:退出会话,重做第 6 步再启动。新终端仍读到旧值时关闭全部终端再开,必要时注销后登录 Windows。
卡住了?按报错处理
| 现象 | 处理 |
|---|---|
node / npm.cmd 无法识别 | 关闭全部终端再开;仍失败则用 Node.js 安装包 Repair,保留 npm 与 Add to PATH。 |
EBADENGINE / Node 版本低 | 安装 Node.js 24 LTS;仍显示旧版本,用 Get-Command node -All 查重复安装。 |
git 无法识别 / 找不到 Git Bash | 重开终端,检查第 3 步 PATH 选项。自定义路径用 where.exe git 定位;CLAUDE_CODE_GIT_BASH_PATH 应指向 bin\bash.exe,不是 git-bash.exe。 |
npm 下载慢 / ETIMEDOUT / ECONNRESET | 按 Ctrl+C 停止,检查网络;仅 npm 源受阻时参考下方镜像说明。 |
| 下载 403 / 地区提示 / HTML | 核对失败地址、系统时间和官方下载网络,不把网页 HTML 当安装脚本执行。 |
EPERM / EACCES / 文件占用 | 退出所有 Claude Code 再安装;仍失败请管理员检查 npm 目录权限及安全软件,不删整个 npm 目录。 |
claude.cmd 无法识别 | 重开全部终端,运行下方定位命令,再看 PATH 说明。 |
.ps1 禁止运行脚本 | 完整使用 npm.cmd / claude.cmd。 |
native binary not found | 按官方说明重装平台依赖;不用 --omit=optional 或 --ignore-scripts。[6] |
| 要求官网登录 / 地址不对 / 认证冲突 | 复查第 6 步和 /status;请管理员检查旧认证变量、.claude\settings.json 的 env 及组织登录策略,保留现有配置。 |
401 / Invalid API key | 重新复制个人用户 key,确认账号未过期或停用。 |
403(模型请求) | 请管理员确认账号和模型权限。 |
404 / model not found | 根地址不要多加 /v1;核对完整模型 ID 和渠道支持。 |
402 / quota exceeded | 检查额度、余额及窗口限制。 |
429 / rate limit | 停止连续重试,等待限速恢复。 |
503 / Proxy is not configured | 请管理员恢复可用渠道;暂时无法完成第 8 步。 |
| SSL / certificate 错误 | 检查时间、Windows 更新及组织证书,不关闭 HTTPS 校验。 |
npm.cmd list -g @anthropic-ai/claude-code --depth=0
npm.cmd prefix -g
Get-Command claude.cmd -Allnpm 包已安装,但找不到命令:检查 PATH
- 打开
npm.cmd prefix -g输出的目录,确认存在claude.cmd;没有则回第 4 步。 - 开始菜单搜索「编辑帐户的环境变量」,在当前用户 Path → 编辑 → 新建中添加该目录,保留所有原有项。
- 逐层确定,关闭全部终端再开,重试
claude.cmd --version。受组织管理的电脑请管理员处理。
仅 npm 官方源超时:临时使用国内镜像
npmmirror 是第三方软件源,可能同步延迟。确认信任后,停止上一条安装再运行;无需提供 SHUN key,也不会永久改源。[10]
npm.cmd install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmmirror.com成功后回第 4 步检查版本。缺少平台包时恢复官方源或等待同步,不跳过依赖或证书检查。
求助时提供:Windows 和软件版本、失败步骤、时间与报错。截图遮住 key 和个人资料,不发送整份环境变量或配置文件。
资料来源与版本说明
2026-10-19 核对:官方优先推荐原生安装,也提供 npm 方案。本篇沿用 Node.js → Git → npm 路线,当前 npm 包 2.1.303 要求 Node.js 22+。已核对命令和配置;完整在线成功仍以第 8 步实际文件为准。
下载条件、官方地区支持与 SHUN 模型权限分别检查。以下前九项为官方资料,第十项为第三方镜像说明。
- Claude Code:系统要求、Git 与 npm 安装
- Claude Code:快速开始与首次会话
- Node.js:LTS 与 Windows 官方安装包
- Claude Code:连接 LLM 网关与 /status 检查
- Claude Code:模型配置和环境变量
- Claude Code:安装、PATH 与登录排错
- Git:Windows 官方下载
- Microsoft:环境变量、当前进程与用户作用域
- npm:安装 Node.js 与 npm、选择 LTS
- npmmirror:镜像站的使用说明(第三方软件源)
本站安装指南不读取、收集或保存你的 key。步骤勾选只记在当前浏览器,可随时取消;清理浏览器数据会重置进度。