Claude Code 安装教程与首次配置

📍 文件与编程进阶：Claude Code

Mac 终端窗口示意，命令输入在提示符之后

先分清安装工具和连接模型

装好 Claude Code，只是让电脑上有了这个工具；真正开始任务，还需要可用的模型服务与凭据。 这两步分开做，出错时就比较容易定位。

本文于 2026 年 9 月 26 日核对官方资料，说明命令行版本的安装和首次配置。网络可达性、账号资格与模型费用需要按你实际使用的服务确认，也不承诺固定几分钟装完。Anthropic 不向中国大陆（含港澳）提供服务，官方安装地址和官方账号在大陆都用不了，大陆读者直接按下表「在中国大陆」那一行走。

你现在的情况	从哪里开始
已经能运行 `claude --version`	跳到第三步，选择模型服务
在中国大陆（含港澳）	第二步用 npm 镜像方案安装，第三步选 DeepSeek
第一次安装，能访问官方安装地址	使用第二步的原生安装方式
已在用 Node.js，想用 npm 管理安装	看第二步中的 npm 方案
下载失败	先看报错表，区分网络、版本和权限问题

第一步：打开终端

终端是通过输入命令来操作电脑的窗口。Mac 可以按 Command + 空格，搜索“终端”；Windows 打开 Windows Terminal 的 PowerShell 标签；Linux 打开系统终端。

Windows PowerShell 窗口示意

Windows 的提示符以 PS 开头时，表示正在使用 PowerShell。本文的 Windows 命令都按 PowerShell 编写，别混用 CMD 命令。粘贴通常可以使用 Ctrl + V 或终端菜单；Mac 用 Command + V。

先试一条无须安装软件的命令：

echo hello

看到 hello，说明你已经完成了“输入命令—回车—查看结果”的第一轮操作。

第二步：选择一种安装方式

官方原生安装

Anthropic 当前推荐原生安装。Mac、Linux 或 WSL（在 Windows 里运行 Linux 的子系统）使用：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 使用：

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

这些命令会下载并执行官方安装脚本。执行前核对地址与 Claude Code 官方快速入门一致。

在中国大陆，这两条命令拿到的是「App unavailable in region」网页，不是安装脚本，会报错（见后面的报错表）；Homebrew、WinGet 等其他官方安装方式访问的是同一批地址，也会失败。请直接用下面的 npm 镜像方案。

原生安装不要求你先安装 Node.js。Windows 当前也可以直接使用 PowerShell；安装 Git for Windows后可使用 Git Bash，是否需要它取决于项目工具链。

npm 安装与按次使用镜像

如果你已经使用 npm，也可以通过官方 npm 包安装。在中国大陆也用这个方案：npm 安装只需要能访问 npm 包仓库，不需要访问 Claude 的官方下载地址（见官方网络说明）。先检查：

node --version
npm --version

截至本次核验，Claude Code 的 npm 包要求 Node.js 22 或更高版本。旧教程里“Node 18 就够”不能再作为当前安装要求；以 Anthropic 的 npm 安装说明为准。没有 Node.js 时，从 Node.js 官方下载页选择适合系统的受支持 LTS 版本。

使用官方 npm 源安装：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org

如果你决定使用 npmmirror（国内的 npm 镜像，大陆读者一般选它），可只让这一次安装走镜像：

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

第二条命令使用第三方包镜像，不是模型服务入口。镜像可能有同步延迟或平台包下载问题，不能保证所有版本始终可用；也不需要为此永久修改整台电脑的 npm 仓库设置。

确认程序可以启动

安装完成后重新打开终端，运行：

claude --version

看到版本号，说明程序已经能被找到。这一步还没有验证模型连接。 如果提示找不到命令，先看后面的报错表，不要连续叠装多套版本。

第三步：选择模型服务

使用 Claude 官方账号或组织提供的服务

按官方登录说明启动 claude 并完成对应认证。订阅、API 和组织接入方式不同，以账号当前支持的入口为准。官方账号需要 Pro、Max、Ultra、Team、Enterprise 订阅或 Console 账号，免费账号不含 Claude Code。

Anthropic 不向中国大陆（含港澳）提供服务，Claude 官方账号在大陆注册、订阅、付款都过不去。大陆读者跳过这一节，看下面的 DeepSeek。

使用 DeepSeek API

DeepSeek 提供 Claude Code 官方接入指南。这时你使用的是 Claude Code 工具搭配 DeepSeek 模型，费用也由 DeepSeek 的 API 账单计算。

在 DeepSeek 开放平台创建 API Key，并确认 API 账户可正常使用。聊天产品账号的使用情况不等于 API 账户已有可用额度。

DeepSeek 开放平台登录页的旧版示意

下面先在新开的一个终端窗口里临时配置，便于试用后退出，不改现有启动配置文件。已有公司配置或其他模型服务时，先确认不会混用旧设置。

Mac／Linux：先运行第一行，粘贴 Key 并回车，再运行第二行。输入时不回显字符，也不会把真实 Key 写进命令历史：

read -r -s ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN

接着按本次核验的 DeepSeek 官方配置设置服务与模型；模型名带方括号，保留引号：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
export CLAUDE_CODE_EFFORT_LEVEL="max"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"

Windows PowerShell：先安全输入 Key，再设置其余变量：

$env:ANTHROPIC_AUTH_TOKEN = [System.Net.NetworkCredential]::new("", (Read-Host "DeepSeek API Key" -AsSecureString)).Password
$env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_MODEL = "deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL = "deepseek-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL = "max"
$env:CLAUDE_CODE_AUTO_COMPACT_WINDOW = "786432"

配置仅对当前终端及它启动的程序生效。关闭窗口后，后续新终端不会保留这些设置；打算长期使用时，再确认适合自己的凭据保存方式，模型参数以 DeepSeek 官方接入指南为准。

API Key 要留在本机的凭据管理方式里，别贴到聊天、截图、公开仓库或报错求助中。运行在电脑上的工具仍会向配置的云端模型服务发请求，练习时先用不含私人信息的材料。

第四步：用一个练习目录完成首次任务

Mac／Linux：

mkdir -p ~/ai-practice
cd ~/ai-practice
claude --permission-mode default

Windows PowerShell：

New-Item -ItemType Directory -Force "$HOME\ai-practice" | Out-Null
Set-Location "$HOME\ai-practice"
claude --permission-mode default

--permission-mode default 表示用手动确认模式启动，界面上叫 Manual。新版 Claude Code 默认是 auto 模式，大多数改文件、跑命令的动作不会先问你；第一次练习先用 Manual，看清每一步在做什么。接 DeepSeek 时 auto 大概率本来就用不了，会从 Manual 开始，以状态栏显示为准。

界面首次启动可能还有工作目录信任、权限或账号提示。读清当前选择，不要为了跳过报错而统一放开所有操作。

Claude Code 交互界面的旧版示意，具体菜单可能变化

可以输入这句练习指令：

如果当前目录没有 hello.txt，请新建它并写入“你好，这是我的第一次练习”；如果已存在，先告诉我。完成后读出文件内容，不访问其他目录。

检查目录里是否真的出现了文件，并打开核对内容。到这一步，才是工具、模型连接和一次文件操作都完成了。使用 API 时也可以查看服务后台的本次用量。

跑不起来时，先对照错误

看到的现象	先检查什么
`command not found` 或找不到 `claude`	先重新打开终端。原生安装把 `claude` 放在 `~/.local/bin`（Windows 是 `%USERPROFILE%\.local\bin`），这个目录不在 PATH（系统查找命令用的目录列表）里就会找不到；按官方步骤把它加进去，不要先重复安装
安装命令报 `syntax error near unexpected token '<'`（PowerShell 里是一串引用网页代码的解析错误），或提示 App unavailable in region	安装地址返回的是网页，不是安装脚本，说明你所在地区不在 Anthropic 的支持列表里。换其他官方安装方式也会失败；改用第二步的 npm 镜像方案，模型服务选 DeepSeek
npm 显示 `EBADENGINE`	这只是警告，不是安装失败。先运行 `claude --version`，能显示版本号就可以继续；方便时再把 Node 升级到 22 或更高版本
下载超时、403 或证书错误	核对访问地址、网络和组织策略；不要关闭 TLS 校验（检查网站证书的安全机制）。在中国大陆遇到 403，多半也是地区限制，处理办法同上面 App unavailable in region 那一行
`EACCES` 权限错误	参考官方权限排障，不用 `sudo npm install -g` 强行安装
已配置 Key，仍出现认证或模型错误	检查当前终端是否读到正确服务地址，模型名是否有效，是否残留别的凭据配置
API 提示余额或用量不足	查看实际提供方的 API 账单与限制，不拿聊天会员状态代替检查
刚才能用，关掉窗口后不行	本文先用了临时变量；重新配置，或在确认成功后再设置持久保存

安装与登录问题继续看 Anthropic 官方排障。求助时保留错误文字、系统与版本号，遮住凭据。

常见问题

一定要安装 Node.js 吗？

原生安装不要求先安装 Node.js。选择 npm 方案才需要相应 Node 环境，当前要求见上文的官方说明。

换 npm 镜像就能使用模型吗？

不能。包下载、模型 API、账号资格是不同环节。镜像只解决安装包从哪里下载；安装成功后仍要验证模型连接。

DeepSeek 每月大概花多少？

取决于任务、模型和实际用量，不能承诺固定月费。先用一个小任务查看账单，再决定预算；最新标准见 DeepSeek 官方计费说明。

以后怎么升级？

原生安装会在后台自动更新，想马上更新就运行 claude update。用 npm 装的，运行 npm install -g @anthropic-ai/claude-code@latest；当初用镜像装的，同样在后面加上 --registry=https://registry.npmmirror.com。不要用 npm update -g，它可能升不到最新版。升级后用 claude --version 看版本号。官方升级说明

下一步

完成练习后，继续看第一次任务：从练习文件开始和读文件、改文件。先把一个小任务做对，再逐步扩到自己的工作流程。