Claude Code全平台安装与首项目实战

本教程面向零基础开发者，系统讲解 Claude Code 的运行原理、全平台（macOS/Linux/Windows）安装路径选择、三种认证方式对比决策、项目级配置（CLAUDE.md 与 settings.json），并通过一个完整的可运行 CLI 待办工具项目串起从安装到首次运行的完整链路，附带新手高频报错避坑手册。适合从未接触过 AI 终端工具、希望从图形化 AI 助手迁移到命令行工作流的学习者。

一、概述

Claude Code 是 Anthropic 官方推出的终端原生（terminal-native）AI 编程助手。与 ChatGPT 网页版、Cursor 图形 IDE 不同，它直接运行在你的命令行里，能够读写本地文件、执行 Shell 命令、运行测试、操作 Git，相当于一个理解你整个代码库的「智能同事」坐镇终端。

适用人群： - 从未用过 AI 编程工具、想从零搭起一个真实项目的开发者 - 习惯了网页版 AI 对话、希望让 AI 直接动手改代码的进阶用户 - 需要在团队中标准化 AI 协作流程的工程负责人

学习目标：读完本文，你能独立在任意操作系统装好 Claude Code、完成认证、配置好首个项目，并跑通一个可运行的 CLI 应用，同时掌握排错能力。

二、前置条件

在动手安装之前，请确认你的环境满足以下要求：

关键提醒：Windows 用户强烈建议使用 WSL2（Ubuntu）而非原生 PowerShell。虽然 Claude Code 在 Windows 原生终端下也能运行，但大量构建工具、Shell 脚本、Git 钩子在 WSL 下兼容性远优于原生环境，可避免后续 80% 的「环境问题」。

三、理解安装方式：先做一道选择题

很多人卡在第一步，就是因为没搞清 Claude Code 到底有几种安装方式、彼此有何区别。这里先讲清楚决策逻辑，再给命令。

3.1 两种安装路径

Claude Code 目前提供两条主流安装路径：

1. Native Installer（原生安装器） —— 官方独立二进制，无需 Node.js
2. npm 全局安装 —— 通过 npm install -g 安装 Node 包

3.2 决策矩阵

结论：如果你是零基础、电脑里没有装 Node.js，直接选 Native Installer；如果你是前端/全栈开发者、已经有完整的 Node 环境，npm 安装更贴合既有习惯。

四、各平台安装实操

步骤 1：选择并执行安装命令

方案 A：Native Installer（推荐新手）

# macOS / Linux（含 WSL2）
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell（原生）
irm https://claude.ai/install.ps1 | iex

预期结果：脚本会下载二进制文件并安装到用户目录（通常是 ~/.local/bin 或类似路径），随后自动提示你将路径加入 PATH。安装完成后执行：

claude --version

若输出形如 Claude Code v1.x.x，说明安装成功。

方案 B：npm 全局安装

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

预期结果：npm 会拉取官方包并链接到全局 bin 目录。完成后执行 claude --version 验证。

方案 C：通过 Homebrew（macOS/Linux 可选）

部分版本支持 Homebrew Cask 安装，适合习惯用包管理器的用户：

brew install --cask claude-code

步骤 2：验证 PATH 与可执行性

安装后如果 claude 命令「未找到」，通常是 PATH 未生效：

# macOS / Linux：检查可执行位置
which claude

# 临时加入 PATH（以 zsh 为例）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows 原生安装会把可执行路径写入用户级 PATH，重启 Terminal 即可生效。

五、认证：三种方式的对比与选择

安装完成后，第一次运行 claude 时会要求认证。这里是最容易让新手困惑的地方——究竟用什么登录？答案是：取决于你的账号类型。

5.1 三种认证方式

5.2 决策建议

• 个人学习/副业项目 → 用 Claude 订阅登录，零额外配置
• 公司项目/需要团队共享 → 用 Console API Key，便于账单与配额管理
• 合规要求严格的金融/政企 → 走 Bedrock / Vertex AI 网关

5.3 实操认证

方式一：订阅账号登录（默认）

claude

首次运行会提示你打开浏览器完成 OAuth 授权，授权后终端自动获得凭证。整个过程无需手动复制 Token。

方式二：使用 API Key

# 设置环境变量（推荐写入 shell 配置文件持久化）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

claude

Claude Code 会自动识别环境变量中的 Key 并采用 Console 计费。

方式三：指定自定义网关（企业）

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="your-key"
claude

预期结果：认证成功后，终端会进入交互式会话界面，底部显示当前模型与上下文状态。

六、首次交互：认识 REPL

启动 claude 后进入的就是交互式 REPL（Read-Eval-Print Loop）。它和网页对话框最大的区别是——它能动手。

$ claude
> 帮我看看当前目录有什么文件

Claude 会调用内置的文件浏览工具，列出目录树，并给出解读。常用快捷操作：

• /help —— 查看所有内置斜杠命令
• /model —— 切换模型（Sonnet / Opus / Haiku）
• /clear —— 清空当前会话上下文
• /config —— 打开配置面板
• Esc Esc —— 回溯编辑上一条消息
• Ctrl+C —— 中断当前操作

新手提示：第一次不必急着改代码，先用自然语言让它「描述一下这个项目」，观察它如何调用工具，建立对工作流的直觉。

七、项目配置：让 AI 真正懂你的项目

裸用 Claude Code 已经能干活，但要做到「团队标准化、AI 行为可预测」，必须配置两个核心文件。

7.1 CLAUDE.md —— 项目记忆

在项目根目录创建 CLAUDE.md，把项目的约定、技术栈、命名规范写进去。Claude Code 每次启动会自动读取它作为上下文。

# 项目说明：todo-cli

## 技术栈
- 语言：Node.js 20+，纯 ESM
- 测试：Vitest
- Lint：ESLint + Prettier

## 命名约定
- 函数：camelCase
- 文件：kebab-case
- 常量：UPPER_SNAKE_CASE

## 开发命令
- 安装依赖：`npm install`
- 运行：`npm run dev`
- 测试：`npm test`

作用：避免每次都要重复交代背景，AI 会自觉遵循你的规范。

7.2 settings.json —— 权限与行为

位于 .claude/settings.json，控制工具权限、环境变量、钩子等。新手最该配的是权限白名单，减少反复确认：

{
  "permissions": {
    "allow": [
      "Bash(npm install)",
      "Bash(npm test)",
      "Bash(npm run dev)",
      "Read(**)",
      "Edit(src/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

含义：读取任意文件、编辑 src/ 下文件、运行这三条 npm 命令时自动放行，无需每次手动确认 y/n。其余操作仍会弹确认，保证安全。

八、第一个项目：todo-cli 完整实战

下面用 Claude Code 从零搭建一个可运行的命令行待办工具，串起整个流程。

8.1 初始化项目

mkdir todo-cli && cd todo-cli
git init
npm init -y

8.2 创建 CLAUDE.md

写入第七节的示例内容。然后启动 Claude Code：

claude

8.3 用自然语言下达需求

在 REPL 中输入：

用 Node.js + commander 实现一个 CLI 待办工具，要求：
1. add <内容>  添加任务
2. list        列出所有任务（带序号和完成状态）
3. done <序号> 标记完成
4. 数据用 JSON 持久化到 ~/.todo-cli.json
帮我搭建完整代码，并在 package.json 里配置 bin 和 start 命令。

8.4 预期产出

Claude 会自动安装依赖、生成 src/index.js、更新 package.json。核心代码大致如下：

import { program } from 'commander';
import { readFile, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';

const DB = join(homedir(), '.todo-cli.json');

async function load() {
  try {
    const raw = await readFile(DB, 'utf-8');
    return JSON.parse(raw);
  } catch {
    return [];
  }
}

async function save(todos) {
  await writeFile(DB, JSON.stringify(todos, null, 2));
}

program
  .command('add <text>')
  .description('添加任务')
  .action(async (text) => {
    const todos = await load();
    todos.push({ text, done: false });
    await save(todos);
    console.log(`✅ 已添加：${text}`);
  });

program
  .command('list')
  .description('列出任务')
  .action(async () => {
    const todos = await load();
    if (todos.length === 0) return console.log('（暂无任务）');
    todos.forEach((t, i) => {
      console.log(`${t.done ? '[x]' : '[ ]'} ${i + 1}. ${t.text}`);
    });
  });

program
  .command('done <index>')
  .description('标记完成')
  .action(async (index) => {
    const todos = await load();
    const i = Number(index) - 1;
    if (!todos[i]) return console.log('❌ 序号无效');
    todos[i].done = true;
    await save(todos);
    console.log(`🎉 已完成：${todos[i].text}`);
  });

program.parse();

package.json 关键字段：

{
  "type": "module",
  "bin": { "todo": "src/index.js" },
  "scripts": { "start": "node src/index.js" },
  "dependencies": { "commander": "^12.0.0" }
}

8.5 运行验证

node src/index.js add "学习 Claude Code"
node src/index.js add "写第一个项目"
node src/index.js list
node src/index.js done 1
node src/index.js list

预期输出：

✅ 已添加：学习 Claude Code
✅ 已添加：写第一个项目
[ ] 1. 学习 Claude Code
[ ] 2. 写第一个项目
🎉 已完成：学习 Claude Code
[x] 1. 学习 Claude Code
[ ] 2. 写第一个项目

8.6 让 Claude 处理 Git 提交

帮我创建 .gitignore（忽略 node_modules），然后提交所有文件，commit message 用中文概括本次初始化。

Claude 会自动生成 .gitignore、暂存、提交。注意：根据团队规范，提交前请人工核对 diff。

九、新手高频报错避坑手册

十、整体工作流程图

flowchart TD
    A[确认环境: 终端/联网/账号] --> B{有无 Node.js?}
    B -- 否 --> C[Native Installer 安装]
    B -- 是 --> D[npm 全局安装]
    C --> E[验证 claude --version]
    D --> E
    E --> F{账号类型?}
    F -- 个人订阅 --> G[OAuth 浏览器登录]
    F -- Console --> H[设置 ANTHROPIC_API_KEY]
    F -- 企业 --> I[配置自定义网关]
    G --> J[进入 REPL]
    H --> J
    I --> J
    J --> K[创建项目目录]
    K --> L[编写 CLAUDE.md]
    L --> M[配置 settings.json 权限]
    M --> N[自然语言下达需求]
    N --> O[Claude 调用工具: 读/写/执行]
    O --> P[运行测试验证]
    P --> Q[Git 提交]
    Q --> R[首个项目完成]

十一、延伸阅读

• Claude Code 官方文档首页 —— 最权威的功能与配置参考，建议收藏常查
• Anthropic 官方 GitHub 仓库 —— Issue 区与示例项目，是排错第一现场
• Claude Code 最佳实践（Anthropic 工程博客） —— 官方总结的高效使用技巧
• Anthropic Console 控制台 —— 管理 API Key、查看用量与账单
• MCP（Model Context Protocol）官方站 —— 了解如何接入外部工具，为后续进阶铺路

十二、训练营适用性评估

教学节奏建议：30 分钟讲解原理 → 60 分钟动手安装认证 → 90 分钟做 todo-cli 实战 → 15 分钟答疑避坑。考核点：学员能独立在指定平台完成安装、认证，并跑通一个可执行项目。

参考来源

1. Claude Code 官方文档 — Anthropic 官方出品，涵盖概览、安装、配置、命令参考的权威资料库
2. Claude Code 安装与设置指南 — 官方 Native Installer 与 npm 安装、认证方式的详细步骤说明
3. Claude Code GitHub 官方仓库 — 官方维护的代码库与 Issue 区，是排错与跟进新特性的第一现场
4. Anthropic 官方开发者控制台 — 管理 API Key、查看用量配额与账单的入口
5. Claude Code 最佳实践（Anthropic 工程博客） — 官方工程团队总结的高效使用模式与上下文工程技巧

[!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 等场景全覆盖。