## 概述 本教程面向零基础开发者，聚焦新手最容易卡住的三个环节：**安装方式选择、认证登录、首个交互式会话**。根据 Anthropic 官方支持页数据，安装与认证相关工单占全部工单的绝大多数。学完后你将能独立判断该用原生安装还是 npm、该用订阅登录还是 API Key，并跑通第一个完整会话。适用人群：从未用过 Claude Code、希望快速进入正式开发流程的开发者。 ## 前置条件 - 一台 macOS、Linux 或 Windows（含 WSL2）机器，能访问外网 - 终端基础操作（会 `cd`、`ls`、编辑配置文件） - 一个可用的 Anthropic 账号体系：**Claude.ai 订阅**（Pro / Max / Team / Enterprise）**或** Anthropic Console 的 API Key（按量付费） - 无需预先安装 Node.js（若选原生安装）；若选 npm 方式则需 Node.js 18+ ## 核心概念：为什么"认证登录"是新手第一道坎 很多人以为 Claude Code 装完就能用，结果卡在第一步的报错。原因在于 Claude Code 有**三条完全独立的认证路径**，对应两种完全不同的计费方式。选错路径，轻则报 401，重则在订阅额度里烧钱或在 API 余额里烧钱却浑然不知。 理解下面这张决策图，比记住任何命令都重要： ```mermaid flowchart TD A[准备登录 Claude Code] --> B{如何为 Claude 付费?} B -->|Claude.ai 月付订阅| C[订阅 OAuth 登录] B -->|Console 按量计费| D[API Key 登录] B -->|公司统一管理| E[Teams / Enterprise SSO] C --> C1[运行 claude → 选 Claude.ai account] C1 --> C2[浏览器跳转 → 授权] C2 --> C3[Token 存入 Keychain / credentials.json] C3 --> F[受订阅额度限制
Pro 较少 / Max 较多] D --> D1[console.anthropic.com 创建 Key] D1 --> D2[设置 ANTHROPIC_API_KEY 环境变量] D2 --> F2[按 token 计费
适合 CI/CD 与重度调用] E --> E1[管理员分配席位] E1 --> E2[SSO / API Key 接入] ``` 记牢一个原则：**订阅登录走浏览器、API Key 走环境变量，两者不要混用**。如果你既设了 `ANTHROPIC_API_KEY` 又点了订阅登录，Claude Code 通常会优先用环境变量里的 Key，导致你以为在用订阅额度、实际在烧 API 余额。 ## 第一步：选择并完成安装 Claude Code 现在有四种官方安装方式。2026 年 4 月起，**原生安装器（native installer）成为官方推荐默认方式**，因为它不依赖 Node.js、不碰 npm 全局目录，从根源上消灭了新手最常遇到的 EACCES 权限报错。 ### 操作说明 **方式 A — 原生安装器（推荐，适合绝大多数人）** macOS / Linux / WSL： ```bash curl -fsSL https://claude.ai/install.sh | bash ``` Windows PowerShell： ```powershell irm https://claude.ai/install.ps1 | iex ``` > 安装脚本路径以官方 Advanced setup 页面为准，执行前建议 `curl` 下来看一眼内容再 `| bash`，这是良好的安全习惯。 **方式 B — npm 全局安装（已有 Node.js 环境的开发者）** ```bash npm install -g @anthropic-ai/claude-code ``` **方式 C — Homebrew（macOS）** ```bash brew install --cask claude-code ``` **方式 D — winget（Windows 原生）** ```powershell winget install Anthropic.ClaudeCode ``` ### 预期结果 安装完成后运行版本检查： ```bash claude --version ``` 正常会输出形如 `2.x.x` 的版本号。若你用的是原生安装器，二进制通常位于 `~/.local/bin/claude`（或 Windows 的用户目录下），更新会自动进行。 ### 常见问题与解决方案 | 报错现象 | 根因 | 解决方案 | |---------|------|---------| | `claude: command not found`（刚装完立刻出现） | 安装器已把 `claude` 加入 PATH，但当前 shell 尚未刷新 | **打开一个新终端窗口**，或 `source ~/.zshrc`（zsh）/ `source ~/.bashrc`（bash）。这是官方工单第 1 名问题 | | `npm ERR! Error: EACCES: permission denied` | npm 全局目录 `/usr/local/lib/node_modules` 无写权限 | **不要用 sudo**。改用 nvm 管理 Node，或配置用户级 npm prefix：`npm config set prefix ~/.npm-global`，再把 `~/.npm-global/bin` 加进 PATH | | `command not found: claude`（macOS zsh 持续报错） | PATH 未正确写入 shell 配置 | 手动在 `~/.zshrc` 追加 `export PATH="$HOME/.local/bin:$PATH"`，再 `source` | | Windows 下装在 PowerShell 里但 VS Code 终端找不到 | 终端类型差异 / 未重启 VS Code | 重启 VS Code；或统一改用 WSL 终端 | | 网络超时 / SSL 校验失败 | 公司代理或防火墙拦截 | 设置 `HTTPS_PROXY` 与 `HTTP_PROXY` 环境变量指向代理地址 | > **铁律**：npm 全局安装遇到权限问题，**永远不要 `sudo npm install -g`**。它会污染系统目录、带来权限残留，后续所有全局包都会出问题。用 nvm 或自定义 prefix 才是正解。 ## 第二步：完成认证登录 安装成功后，第一次运行 `claude` 会进入认证引导。这是新手最容易踩坑的环节，务必看清楚选项。 ### 操作说明 **路径一：用 Claude.ai 订阅登录（OAuth）** ```bash claude ``` 首次运行会弹出交互菜单，选择 **"Claude.ai account"**（订阅方式）。随后终端会显示一个 URL 和一段 device code，浏览器自动打开（或你手动复制 URL 到浏览器）： 1. 在浏览器登录你的 Claude.ai 账号 2. 确认屏幕上的 device code 与终端一致 3. 点击 Authorize / 授权 4. 终端显示 `Logged in successfully` 即完成 授权后，OAuth token 会安全存储在 **macOS Keychain** 或 **`~/.claude/.credentials.json`**（其他平台），后续无需重复登录。 **路径二：用 API Key 登录（按量付费）** 先到 [console.anthropic.com](https://console.anthropic.com) 创建一个 API Key（以 `sk-ant-` 开头），然后设置环境变量： ```bash # macOS / Linux / WSL —— 写入 shell 配置持久化 echo 'export ANTHROPIC_API_KEY="sk-ant-你的key"' >> ~/.zshrc source ~/.zshrc # Windows PowerShell（当前会话） $env:ANTHROPIC_API_KEY="sk-ant-你的key" ``` 设置后直接运行 `claude` 即可，无需再走浏览器流程。 > **安全提示**：API Key 是敏感凭据。永远不要把它写进代码仓库、截图或聊天记录。建议放进系统 keychain（macOS 可用 `security` 命令）或 `.env` 文件并加入 `.gitignore`。 ### 预期结果 登录成功后，运行任意命令验证连通性，比如进入一个目录后： ```bash claude -p "say hello in one word" ``` 正常会返回模型的一个简短回答，说明认证与网络通路均已打通。 ### 常见问题与解决方案 | 报错现象 | 根因 | 解决方案 | |---------|------|---------| | `Authentication failed` / 401 | token 过期或 API Key 失效 | 订阅方式重跑 `claude /login` 重新授权；API Key 方式重新生成 Key 并更新环境变量 | | WSL 下浏览器无法自动打开 | WSL 无图形浏览器 | 手动复制终端里的 URL 到 Windows 浏览器，复制回 device code；或在 WSL 配置 `BROWSER` 指向 Windows 浏览器 | | 订阅登录后仍提示额度耗尽 | 你设了 `ANTHROPIC_API_KEY` 环境变量，覆盖了订阅凭证 | `unset ANTHROPIC_API_KEY` 并从 shell 配置删除该行，重跑 `/login` | | `Region not supported` | 账号所在地区不被服务 | 检查账号注册地区，必要时联系 Anthropic 支持或在受支持地区操作 | | OAuth 授权页一直转圈 | 浏览器缓存或代理拦截 | 换无痕窗口重试；检查代理是否放行 `claude.ai` 域名 | ## 第三步：跑通首个交互式会话 认证完成后，进入真正的使用环节。理解**斜杠命令**和**权限提示**这两件事，你就算真正入门了。 ### 操作说明 新建或进入一个项目目录： ```bash mkdir hello-claude && cd hello-claude claude ``` 进入交互式界面（REPL）后，光标处可以直接用自然语言对话。几个必须知道的斜杠命令： | 命令 | 作用 | |------|------| | `/help` | 查看所有可用命令 | | `/init` | 让 Claude 分析当前项目并生成 `CLAUDE.md` 记忆文件 | | `/clear` | 清空当前对话上下文（开始新任务前常用） | | `/config` | 打开配置面板，切换主题、模型等 | | `/model` | 切换模型（如 Sonnet / Opus） | | `/login` | 切换或新增登录账号 | | `/cost` | 查看本次会话已消耗的 token 与费用 | ### 预期结果 当 Claude 要执行**写文件**或**运行命令**等有副作用的操作时，会先弹出权限确认提示，例如： ``` Claude wants to run: npm install Allow? (y)es / (n)o / (a)lways allow for this project ``` 这是 Claude Code 的安全护栏。你逐项确认即可。选 `a` 会让它在本项目内自动放行该类操作（写入 `.claude/settings.local.json`）。 ### 常见问题与解决方案 - **每次都要确认，太烦**：合理使用 `a`（always）减少打扰，或在 `/config` 中调整权限模式为更宽松的级别（个人项目可用，团队/生产仓库慎用）。 - **回答跑偏、上下文混乱**：复杂任务开始前先 `/clear`，避免把无关历史塞进上下文。 - **模型选错导致又慢又贵**：简单任务用 Sonnet，复杂架构/重构用 Opus；用 `/model` 随时切换。 ## 实战案例：5 分钟跑通"安装—登录—首个会话"全流程 下面是一个零基础用户从零到能用 Claude Code 改代码的完整流程，照做即可。 ```bash # 1. 安装（macOS / Linux，用原生安装器） curl -fsSL https://claude.ai/install.sh | bash # 2. 刷新 shell，验证 source ~/.zshrc # 或 ~/.bashrc claude --version # 应输出版本号 # 3. 首次运行，选 "Claude.ai account" 走浏览器 OAuth 订阅登录 claude # 4. 进入一个真实项目（这里用 git clone 一个示例） git clone https://github.com/octocat/Hello-World.git cd Hello-World claude # 5. 在 REPL 里让 Claude 生成项目记忆 > /init # 6. 下达第一个真实任务（自然语言） > 在 README 末尾追加一行 "Powered by Claude Code"，并说明改动 # 7. 确认权限提示（写文件 → y），查看改动 > 用 git diff 给我看改动 # 8. 查看本次消耗 > /cost # 9. 退出 > /quit # 或 Ctrl+C 两次 ``` **预期结果**：你会看到 Claude 自动读取项目、调用工具修改 `README`、提交权限请求、用 `git diff` 展示改动。整条链路跑通，就证明你的安装、认证、会话三层都正确无误。 ## 整体工作流全景 把前面的所有环节串起来，一个新手的完整入门路径如下： ```text flowchart LR A[确认付费方式
订阅 or API Key] --> B[选择安装方式
原生/npm/brew/winget] B --> C[运行安装脚本] C --> D{claude --version 成功?} D -- 否 --> E[排查 PATH/权限/EACCES] E --> C D -- 是 --> F[首次运行 claude] F --> G{认证方式} G -- 订阅 --> H[浏览器 OAuth 授权] G -- API Key --> I[设置 ANTHROPIC_API_KEY] H --> J[进入项目目录] I --> J J --> K[claude 启动 REPL] K --> L[/init 生成 CLAUDE.md] L --> M[下达自然语言任务] M --> N[确认权限提示] N --> O[查看改动与 /cost] O --> P[🎉 入门完成] ``` ## 延伸阅读 - **Claude Code 官方文档** — [code.claude.com/docs](https://code.claude.com/docs) ：安装、认证、配置的权威来源，建议加入书签 - **官方认证文档** — [Authentication](https://code.claude.com/docs/en/authentication) ：订阅、API Key、企业 SSO 的完整说明 - **官方安装排障** — [Troubleshoot installation and authentication](https://support.claude.com/en/articles/14552646-troubleshoot-claude-code-installation-and-authentication) ：十大高频工单与官方修复方案 - **Claude Code Quickstart** — 官方首个会话引导 `/en/quickstart`，配合本教程的认证环节一起看 - **WSL 安装专题** — 社区维护的 Windows 子系统安装指南，解决 Windows 用户的路径与浏览器跳转问题 ## 训练营适用性评估 - **适合类型**：所有以 Claude Code 为工具栈的**入门训练营**（前端、后端、全栈、AI 应用开发均可作为第 1 课） - **教学时长**：建议 **1.5–2 小时**（讲授 40 分钟 + 动手实操 60 分钟 + 答疑 20 分钟） - **分组建议**：按操作系统分组（macOS / Linux / Windows+WSL），每组配一位助教专门解决认证与环境问题，可大幅降低卡壳率 - **考核标准**：学员独立完成"安装 → 登录 → `/init` → 一次有效代码修改 → `/cost` 查看"全链路即算通过 - **后续衔接**：本课为后续 Skills 开发、MCP 集成、自动化 Hooks 等高阶主题的前置必修，务必让全员跑通后再进入下一模块 - **风险提示**：网络环境受限的地区需提前准备代理方案；API Key 方式的学员需提前在 Console 充值少量额度用于实操，避免课中余额不足中断 ## 参考来源 1. [Troubleshoot Claude Code installation and authentication — Claude Help Center](https://support.claude.com/en/articles/14552646-troubleshoot-claude-code-installation-and-authentication) — Anthropic 官方十大高频安装/认证工单与修复方案（官方支持文档） 2. [Authentication — Claude Code Docs](https://code.claude.com/docs/en/authentication) — 订阅 OAuth、API Key、Teams/Enterprise SSO 三条认证路径的官方权威说明（官方文档） 3. [Advanced setup — Claude Code Docs](https://code.claude.com/docs/en/setup) — 原生安装器、npm、Homebrew、winget 四种安装方式与系统要求（官方文档） 4. [Claude Code on Claude Max Plan: Understanding OAuth Token vs API Key Authentication — Medium](https://lalatenduswain.medium.com/claude-code-on-claude-max-plan-understanding-oauth-token-vs-api-key-authentication-in-2026-96a6213d2cde) — 订阅 OAuth token 与 API Key 计费差异的技术博客分析（技术博客） 5. [How to Install Claude Code on Windows, macOS & Linux Guide — FindSkill.ai](https://findskill.ai/blog/install-claude-code-setup-guide/) — 2026 年原生安装器为默认方式的多平台安装教程与路径排错（教程站） > [!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 等场景全覆盖。