## 概述
本教程面向**从未用过命令行 AI 编程工具**的零基础读者，目标是用约 20 分钟完成三件事：在 macOS / Linux / Windows 上把 Claude Code 装好、看懂它的「四层配置体系」并写出第一份配置、再用它跑通一个真正会输出结果的小项目（代码行数统计器）。读完后你将能独立判断安装方式、知道 `settings.json` 该放哪里、并体验完整的「提问 → 评审 → 运行 → 提交」循环。
## 前置条件
- 一台能联网的电脑（macOS / Linux / Windows 均可，Windows 推荐用 WSL）
- 会打开终端、能执行 `cd`、`ls` 这类基础命令即可
- 一个 Claude 订阅（Pro / Max / Team / Enterprise），或 Claude Console 账号（API 预付费额度）
- 选装：Git（强烈建议，作为改动安全网）
> 不必先装 Node.js。官方现已提供**原生安装器**，不再强制依赖 npm/Node。
---
## 第一步：选择并执行安装方式
官方文档给出四种安装途径，下表是它们的核心差异：
| 方式 | 命令（macOS/Linux/WSL） | 自动更新 | 适用场景 |
|---|---|---|---|
| **原生安装器（推荐）** | `curl -fsSL https://claude.ai/install.sh \| bash` | ✅ 后台静默更新 | 大多数个人用户 |
| Homebrew | `brew install --cask claude-code` | ❌ 需手动 `brew upgrade` | 已用 brew 管理软件的 Mac 用户 |
| WinGet（Windows） | `winget install Anthropic.ClaudeCode` | ❌ 需手动升级 | 纯 Windows 用户 |
| npm | `npm install -g @anthropic-ai/claude-code` | ❌ | 已有 Node 环境的老用户 |
**Windows 补充**：PowerShell 用 `irm https://claude.ai/install.ps1 | iex`；CMD 用 `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`。原生 Windows 下建议额外装 **Git for Windows**，否则 Claude Code 会退回用 PowerShell 当 shell。
**验证安装是否成功**：装完新开一个终端，执行：
```bash
claude --version
```
能看到版本号即说明 `claude` 已进入 PATH。若提示「command not found」，多半是终端没重开（PATH 未刷新）——重开终端再试，这是新手最高频的踩坑点。
**常见问题**
- 报 `syntax error near unexpected token '<'` 或 403：通常是网络代理把脚本内容改写了，挂代理或换网络重试。
- PowerShell 报 `'irm' is not recognized`：说明你其实在 CMD 里，换用 CMD 那行命令。
- npm 方式报权限错误（EACCES）：改用原生安装器，能彻底避开 npm 全局目录权限问题。
---
## 第二步：登录与凭证存储
在任意目录输入 `claude` 启动首次会话，会触发浏览器登录。三种账号类型任选其一：
1. **Claude Pro / Max / Team / Enterprise**（推荐）：订阅用户，跟随订阅额度。
2. **Claude Console**：API 预付费额度，首次登录会自动建一个名为「Claude Code」的工作区用于成本汇总。
3. **Amazon Bedrock / Google Vertex AI / Microsoft Foundry**：企业云厂商接入。
登录成功后凭证会**存储在本机**，之后无需重复登录；想换账号时在会话里输入 `/login`。环境变量鉴权（`ANTHROPIC_API_KEY`）适合脚本/CI，但本入门篇建议先用浏览器交互登录，最直观。
---
## 第三步：看懂「四层配置体系」（核心）
这是新手最容易忽略、却决定你后续一切自定义体验的基础。Claude Code 的配置不是单一文件，而是**分层叠加**的体系。理解了「有哪些文件、谁覆盖谁」，你才知道设置该写到哪里。
官方按作用范围划分出四类作用域（scope）：
| 作用域 | 文件位置 | 影响谁 | 是否随 git 共享 |
|---|---|---|---|
| **Managed（管理员）** | `managed-settings.json`（Linux 在 `/etc/claude-code/`） | 全机器/全组织 | 由 IT 部署 |
| **User（用户）** | `~/.claude/settings.json` | 你，跨所有项目 | ❌ 个人配置 |
| **Project（项目）** | `.claude/settings.json` | 该仓库所有协作者 | ✅ 提交进 git |
| **Local（本地）** | `.claude/settings.local.json` | 只有你，仅本项目 | ❌ 自动加入 gitignore |
**优先级（从高到低）**：Managed ＞ 命令行参数 ＞ Local ＞ Project ＞ User。即项目设置会覆盖用户设置，本地设置又会覆盖项目设置；管理员策略谁也覆盖不了。
> ⚠️ 关键细节：**单值字段是「覆盖」，数组字段是「合并去重」**。例如 `model` 这种字段，高优先级直接覆盖；而 `permissions.allow[]`、`hooks` 这类数组，会把各层来源**拼接在一起**而非互相覆盖——所以你的全局权限规则和项目规则能共存。
这条「覆盖 vs 合并」规则，是 Vincent 博客里点出的、很多人用了一两年都没搞清楚的点，记住它能避免「我明明在用户级配了，怎么项目里不生效」的困惑。
---
## 第四步：写入你的第一份配置
新手只需掌握 **User / Project / Local** 三个可写层。下面动手建一个最小可用配置。
**4.1 用户级配置**（对你所有项目生效，例如固定模型）：
```bash
# 文件：~/.claude/settings.json
```
```json
{
"model": "claude-sonnet-4-6",
"cleanupPeriodDays": 60
}
```
**4.2 项目级配置**（团队共享，进项目根目录操作）：
```bash
mkdir -p .claude
# 文件：.claude/settings.json —— 这个文件会提交到 git
```
```json
{
"permissions": {
"allow": ["Bash(python3:*)", "Bash(git:*)"]
},
"language": "english"
}
```
**4.3 本地覆盖**（只你本人、仅本项目，如临时换更强模型）：
```json
// 文件：.claude/settings.local.json —— Claude Code 会自动把它加进 .gitignore
{
"model": "claude-opus-4-6"
}
```
**快速验证**：在会话里输入 `/config` 会打开设置界面查看当前生效值；从 **v2.1.181** 起，还能用 `/config model=claude-sonnet-4-6` 这种 `key=value` 写法单条改，无需打开整个界面。
---
## 第五步：第一个项目——代码行数统计器（完整闭环）
目标：让 Claude Code 帮你写一个 Python 小工具 `codelines.py`，扫描当前目录并打印按语言分组的文件数与代码行数。它纯标准库、无需联网、输出直观，非常适合体会整套协作循环。
**5.0 安全网**：先初始化 Git，方便随时回滚。
```bash
mkdir my-first-cc && cd my-first-cc
git init
```
**5.1 用具体指令提问**（避免「帮我写个统计工具」这种模糊话）：
```
创建 codelines.py：用 Python 标准库遍历当前目录，按扩展名归类
（.py→Python、.js→JavaScript、.ts→TypeScript、.md→Markdown），
统计每个语言的文件数和总行数，跳过 .git/node_modules/__pycache__，
最后按行数降序打印一张带 ASCII 条形图的表格。
```
Claude Code 会先展示它**打算怎么做**（计划/将改动的文件），征求你同意后再写入。它生成的脚本大致长这样：
```python
# codelines.py — 统计目录下各类代码文件的行数
import os, sys, collections
EXT_LANG = {".py": "Python", ".js": "JavaScript",
".ts": "TypeScript", ".md": "Markdown"}
SKIP_DIRS = {".git", "node_modules", "__pycache__", "venv"}
def count_lines(path):
try:
with open(path, encoding="utf-8", errors="ignore") as f:
return sum(1 for _ in f)
except Exception:
return 0
def walk(root):
stats = collections.defaultdict(lambda: [0, 0]) # lang -> [files, lines]
for dirpath, dirs, files in os.walk(root):
dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
for fn in files:
lang = EXT_LANG.get(os.path.splitext(fn)[1])
if lang:
n = count_lines(os.path.join(dirpath, fn))
stats[lang][0] += 1
stats[lang][1] += n
return stats
def bar(n, total, width=30):
return "█" * int(n / total * width) if total else ""
def main():
root = sys.argv[1] if len(sys.argv) > 1 else "."
stats = walk(root)
total_files = sum(v[0] for v in stats.values())
total_lines = sum(v[1] for v in stats.values())
print(f"\n📊 代码统计：{root}\n" + "-" * 46)
for lang, (files, lines) in sorted(stats.items(), key=lambda x: -x[1][1]):
print(f"{lang:12} {files:>4} 文件 {lines:>7} 行 {bar(lines, total_lines)}")
print("-" * 46)
print(f"合计 {total_files:>4} 文件 {total_lines:>7} 行\n")
if __name__ == "__main__":
main()
```
**5.2 运行并迭代**（这是核心环节，通常要 2–3 轮调整）：
```bash
python3 codelines.py
```
预期输出形如：
```
📊 代码统计：.
----------------------------------------------
Python 3 文件 142 行 ████████████
Markdown 2 文件 48 行 ████
JavaScript 1 文件 30 文件 220 行
```
如果输出不如意，用具体追问让 Claude 改，例如：「把条形图宽度改成 20，并给每行加上占总行数的百分比」「再支持 `-r` 参数限制只统计某种语言」。**每次改动前它会再次征求同意**，这就是评审环节。
**5.3 让 Claude 帮你提交**：
```
把改动用一句描述性信息提交
```
它会生成合适的 commit message 并执行（默认不会自动 push，符合安全预期）。
**常见问题**
- 「它改完没变化」：检查是否在「Accept all」模式下被静默应用了；新手建议保持逐条审批。
- 中文输出乱码：Windows CMD 默认 GBK，在脚本里 `open(..., encoding="utf-8")` 已规避，或换用 WSL。
- 跑 `python3` 报找不到命令：macOS/部分 Linux 上可能是 `python`，让 Claude 顺手加个 README 说明。
---
## 整体工作流与配置优先级（Mermaid）
**入门首跑完整流程**：
```mermaid
flowchart TD
A[空白终端] --> B[执行原生安装器]
B --> C[claude --version 验证]
C --> D[claude 首次登录]
D --> E[git init 建安全网]
E --> F[写 User/Project 配置]
F --> G[具体指令提需求]
G --> H[评审 Claude 的计划]
H --> I[批准并写入文件]
I --> J[运行 python3 codelines.py]
J --> K{输出符合预期?}
K -- 否 --> G
K -- 是 --> L[提交到 Git]
L --> M[首跑通关 🎉]
```
**四层配置优先级（高 → 低）**：
```mermaid
flowchart TD
M["Managed 管理员
managed-settings.json（不可覆盖）"] --> CLI["命令行参数
--settings（临时）"]
CLI --> L["Local 本地
.claude/settings.local.json"]
L --> P["Project 项目
.claude/settings.json（随 git）"]
P --> U["User 用户
~/.claude/settings.json（个人）"]
style M fill:#ffd6d6
style U fill:#d6e8ff
```
> 记住一条例外：**单值字段覆盖，数组字段（permissions/hooks）合并去重**。
---
## 延伸阅读
- **官方 Quickstart**：`code.claude.com/docs/en/quickstart`——8 步上手与本教程互补，含 Git 会话命令清单。
- **官方 Settings 文档**：`code.claude.com/docs/en/settings`——作用域与优先级的权威出处。
- **`/config` 与 `/help`**：会话内随时输入，前者改配置、后者查命令，比记文档更快。
- 进阶可继续了解 `CLAUDE.md`（项目记忆）、Hooks（自动化护栏）、MCP（外接工具），它们都建立在本文的四层配置之上。
## 训练营适用性评估
| 维度 | 评估 |
|---|---|
| 适合的训练营类型 | AI 编程零基础营、企业新员工 AI 上手营、高校编程入门营 |
| 学员基础要求 | 会基本终端命令即可，无需任何编程经验 |
| 建议教学时长 | 引导讲解 60–75 分钟 + 自由动手 30 分钟 |
| 考核点 | 能独立装通并 `claude --version` 通过；能说出配置该写到哪一层；`codelines.py` 跑出统计结果 |
| 常见踩坑 | PATH 未刷新、把个人配置误提交进 git、模糊提问导致输出不可用 |
本教程定位为整个 Claude Code 训练营的**第 1 课地基**：装好、配对、跑通。后续 Skills、MCP、Hooks 等进阶课，都依赖你在这里建立的「四层配置」心智模型。
## 参考来源
1. [Quickstart — Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方安装、登录、首会话与常用命令权威指南
2. [Claude Code settings — Claude Code Docs](https://code.claude.com/docs/en/settings) — 四类作用域、优先级、settings.json 文件体系的官方定义
3. [Claude Code settings.json 配置详解：5 层优先级、3 种文件路径](https://blog.vincentqiao.com/claude-code-settings-intro/) — 中文社区对配置分层、覆盖与合并规则的细致拆解
4. [Claude Code for Beginners: Your First Project in 30 Minutes](https://www.lowcode.agency/blog/claude-code-first-project-tutorial) — 英文新手首项目实战，强调 CLAUDE.md、计划模式与 Git 安全网
5. [Your first day in Claude Code — Claude Help Center](https://support.claude.com/en/articles/14552382-your-first-day-in-claude-code) — 官方 15 分钟从安装到首次 AI 改码的引导
> [!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 等场景全覆盖。
