本教程面向第一次接触 Claude Code 的零基础开发者。2026 年官方已把原生安装脚本(install.sh)列为首推方式——零依赖、免装 Node.js、后台自动更新。本教程横向对比原生脚本、npm、Homebrew 三种安装法,带你完成从选型、安装、认证到跑通第一个项目的全流程,并附三法对比表、故障排查与一个可运行的实战项目。读完即可独立搭建并验证自己的 Claude Code 环境。
正式动手前,先核对清单,避免中途卡壳:
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | macOS 13+ / Ubuntu 20.04+ / Debian 10+ / Windows 10(1809+) + WSL | Windows 推荐 WSL,PowerShell 原生安装也支持 |
| 内存 | ≥ 4GB(8GB 更佳) | 本地只跑 CLI,AI 推理在云端 |
| 网络 | 需稳定连接 Anthropic 云 API | 不需要 GPU |
| 账号 | Claude Pro / Max / Teams / Enterprise,或 Console API Key | 免费版 Claude.ai 不含 Claude Code |
| 终端 | Bash / Zsh / PowerShell | 任一即可 |
| Node.js | 仅 npm 装法需要 18+ | 原生脚本与 Homebrew 装法不需要 |
一句话:只要你有一个 Claude 付费/API 账号、能上网的电脑,五分钟就能装好。
这是 2026 年 Anthropic 主要测试和维护的方式。它把一个独立的 Claude Code 二进制直接放进系统 PATH,不依赖 Node.js、不依赖 npm,并且在后台自动更新。
macOS / Linux:
curl -fsSL https://claude.ai/install.sh | bash
Windows(PowerShell,管理员身份):
irm https://claude.ai/install.ps1 | iex
预期结果:
Downloading Claude Code... 100%
Installing to ~/.local/bin/claude
Adding to PATH...
✓ Installation complete. Run `claude` to get started.
整个过程通常不到一分钟。装完打开一个新终端窗口让 PATH 生效,然后验证:
claude --version
claude doctor
claude doctor 会自检环境并报告任何配置问题,新手第一次跑用它最稳。
常见问题:
command not found: claude:八成是 PATH 没刷新。新开一个终端窗口即可;若仍不行,重跑一次安装脚本。Network Error / 超时:网络或防火墙拦截了脚本下载。先确认能访问 claude.ai;企业内网可配置代理(见下文 npm 小节)。如果你团队里 npm 是标准工作流、或需要把 Claude Code 锁在某个特定版本,用 npm:
npm install -g @anthropic-ai/claude-code
⚠️ 铁律:不要用 sudo。 sudo npm install -g 是权限灾难的起点(EACCES 错误、文件属主错乱)。正确做法是用 nvm 把 Node 装到家目录:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 关闭重开终端
nvm install 22
nvm use 22
node --version # 应输出 v22.x.x
npm install -g @anthropic-ai/claude-code
更新也走 npm:
npm update -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest # 装指定版本
常见问题:
Node.js version too old:node --version 低于 18。用 nvm 装 22。EACCES 权限错误:禁用 sudo,改用 nvm(如上)。bash
npm config set registry https://registry.npmmirror.com/
# 或走代理
npm config set proxy http://your-proxy:8080
npm config set https-proxy http://your-proxy:8080macOS 用户若已习惯 brew,一行搞定:
brew install --cask claude-code
更新:
brew upgrade --cask claude-code
适合已经在用 Homebrew 管理全机软件的 Mac 用户,更新与其他 cask 统一。Linux/Windows 不适用。
| 维度 | 原生脚本 | npm | Homebrew |
|---|---|---|---|
| 依赖 Node.js | ❌ 不需要 | ✅ 需要 18+ | ❌ 不需要 |
| 安装命令 | curl … install.sh |
npm i -g … |
brew install --cask … |
| 自动更新 | ✅ 后台静默 | ❌ 手动 | ❌ 手动(brew upgrade) |
| 版本锁定 | ❌ | ✅ 可 @版本 |
⚠️ 较弱 |
| 跨平台 | mac/Linux/Win | 全平台 | 仅 macOS |
| 适合人群 | 零基础首选 | CI/CD、锁版本团队 | brew 重度用户 |
| 官方推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
选型结论:个人开发、第一次装 → 原生脚本;CI/CD 流水线、要钉死版本 → npm;Mac 上 everything-in-brew → Homebrew。
装好后必须认证。在任意目录运行:
claude
首次会自动打开默认浏览器,登录你的 Anthropic 账号并授权。两种方式:
bash
export ANTHROPIC_API_KEY=sk-ant-your-key-here
claude
Key 在 console.anthropic.com 生成。订阅版(Pro/Max)按月含额度;API Key 按 token 计费。远程服务器或 WSL 里浏览器打不开时,直接用 API Key 方式登录最省心。
目标:用刚装好的 Claude Code,从零搭一个 Python 命令行"待办管理器",验证整套环境跑通。
第 1 步:建项目目录并初始化 Git(方便随时回滚)
mkdir ~/todo-cli && cd ~/todo-cli
git init
echo "# Todo CLI" > README.md
第 2 步:启动交互会话
claude
进入会话后,Claude Code 已读取当前目录结构。输入任务:
> 用 Python 写一个命令行待办管理器 todo.py:
> 支持 add/list/done/delete 四个子命令,数据存到 todos.json。
> 给 add/list 写好用法说明,list 按未完成在前排序。
预期结果: Claude Code 会定位到合适文件、提出改动,并在修改前逐一请求你确认。你可在 diff 视图中逐处接受或拒绝。最终生成 todo.py:
import json, sys, os
from pathlib import Path
DB = Path(__file__).parent / "todos.json"
def load():
return json.loads(DB.read_text()) if DB.exists() else []
def save(todos):
DB.write_text(json.dumps(todos, ensure_ascii=False, indent=2))
def main():
args = sys.argv[1:]
if not args or args[0] in ("-h", "--help"):
print("用法: todo.py [add <text> | list | done <id> | delete <id>]")
return
cmd, todos = args[0], load()
if cmd == "add":
text = " ".join(args[1:])
todos.append({"id": len(todos)+1, "text": text, "done": False})
save(todos); print(f"✓ 已添加 #{len(todos)}: {text}")
elif cmd == "list":
todos.sort(key=lambda t: t["done"]) # 未完成在前
for t in todos:
mark = "[x]" if t["done"] else "[ ]"
print(f"{mark} #{t['id']} {t['text']}")
elif cmd == "done":
for t in todos:
if t["id"] == int(args[1]): t["done"] = True
save(todos); print(f"✓ 已完成 #{args[1]}")
elif cmd == "delete":
todos = [t for t in todos if t["id"] != int(args[1])]
save(todos); print(f"✓ 已删除 #{args[1]}")
if __name__ == "__main__":
main()
第 3 步:让 Claude Code 直接跑测试验证(交互会话里)
> 运行 python todo.py add 买牛奶,再 add 写周报,然后 list,把输出贴给我
预期结果:
✓ 已添加 #1: 买牛奶
✓ 已添加 #2: 写周报
[ ] #1 买牛奶
[ ] #2 写周报
第 4 步:用 -p 做一次性任务(非交互,适合脚本化)
claude -p "给 todo.py 的 delete 命令补充越界 id 的健壮处理,并写一段 50 字内的注释说明改动"
-p 跑完即退出、直接输出结果,常用于快速提问和自动化。
第 5 步(可选):项目级配置 .claude/settings.json
把团队共享的权限/模型约定提交进版本库:
{
"permissions": {
"allow": ["read", "write", "shell"],
"deny": ["shell:rm -rf *"]
},
"model": "claude-sonnet-4-6"
}
个人私有覆盖放在 .claude/settings.local.json(勿提交)。这样一个可运行、可回滚、可协作的 Claude Code 项目就成型了。
从选型到首跑的完整决策与执行链路:
flowchart TD
Start([🚀 想用 Claude Code]) --> Check{核对前置条件<br/>账号+网络+OS}
Check -->|不满足| Fix[补账号 / 装 WSL / 接网络]
Fix --> Check
Check -->|满足| Choose{选安装法}
Choose -->|"个人/首装"| Native[原生脚本<br/>curl install.sh]
Choose -->|"CI/锁版本"| NPM[npm i -g<br/>需 Node18+]
Choose -->|"Mac brew 党"| Brew[brew install --cask]
Native --> Verify
NPM --> Verify
Brew --> Verify
Verify[claude --version<br/>claude doctor] --> Auth{认证}
Auth -->|浏览器| Browser[登录 Pro/Max/Teams]
Auth -->|无头/CI| Key[export ANTHROPIC_API_KEY]
Browser --> Project[cd 项目目录<br/>运行 claude]
Key --> Project
Project --> Task[下任务 → 看 diff → 确认]
Task --> Ship([✅ 首跑成功])
| 维度 | 评估 |
|---|---|
| 适合训练营类型 | AI 编程入门营 / 全栈零基础营 / 企业数字化转型训练营;任何想让学员"第一天就装好工具"的实战型训练营 |
| 学员基础要求 | 会用命令行、懂基本 Git 操作即可;无需 Node/Python 高级知识 |
| 预计教学时长 | 约 45–60 分钟(含环境排查缓冲) |
| 动手实验占比 | 高(70% 动手 + 30% 讲解),三法任选其一装 + 跑通实战项目为结业标准 |
| 风险点 | 国内网络需准备代理/镜像;账号需提前开通 Pro/Max 或 API Key |
| 建议考核 | 学员提交 claude doctor 截图 + 实战项目 list 输出,二者皆绿即通过 |
[!tip] 51学通信知识星球 星主:爱卫生(微信:gprshome201101)——公众号「51学通信」创办者,19 年通信行业运维与讲师经验,著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书(各大电商平台有售)。 星球定位:深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域,主打运维岗位与信令分析。 当前规模:5200 篇主题 / 990 个回答,198 元/年。 加入福利:加入星球后请加爱卫生微信,拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题,另有群内分享。 AI 加持:51学通信知识星球已作为 skill 接入 WorkBuddy,使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例,做总结、找文档和 PPT 等场景全覆盖。
