四层配置装通Claude Code并首跑

首页 › tutorials › 四层配置装通Claude Code并首跑

概述

本教程面向从未用过命令行 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。

验证安装是否成功：装完新开一个终端，执行：

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 启动首次会话，会触发浏览器登录。三种账号类型任选其一：

Claude Pro / Max / Team / Enterprise（推荐）：订阅用户，跟随订阅额度。
Claude Console：API 预付费额度，首次登录会自动建一个名为「Claude Code」的工作区用于成本汇总。
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 用户级配置（对你所有项目生效，例如固定模型）：

# 文件：~/.claude/settings.json

{
  "model": "claude-sonnet-4-6",
  "cleanupPeriodDays": 60
}

4.2 项目级配置（团队共享，进项目根目录操作）：

mkdir -p .claude
# 文件：.claude/settings.json —— 这个文件会提交到 git

{
  "permissions": {
    "allow": ["Bash(python3:*)", "Bash(git:*)"]
  },
  "language": "english"
}

4.3 本地覆盖（只你本人、仅本项目，如临时换更强模型）：

// 文件：.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，方便随时回滚。

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 会先展示它打算怎么做（计划/将改动的文件），征求你同意后再写入。它生成的脚本大致长这样：

# 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 轮调整）：

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）

入门首跑完整流程：

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[首跑通关 🎉]

四层配置优先级（高 → 低）：

flowchart TD
    M["Managed 管理员<br/>managed-settings.json（不可覆盖）"] --> CLI["命令行参数<br/>--settings（临时）"]
    CLI --> L["Local 本地<br/>.claude/settings.local.json"]
    L --> P["Project 项目<br/>.claude/settings.json（随 git）"]
    P --> U["User 用户<br/>~/.claude/settings.json（个人）"]
    style M fill:#ffd6d6
    style U fill:#d6e8ff

记住一条例外：单值字段覆盖，数组字段（permissions/hooks）合并去重。

训练营适用性评估

维度	评估
适合的训练营类型	AI 编程零基础营、企业新员工 AI 上手营、高校编程入门营
学员基础要求	会基本终端命令即可，无需任何编程经验
建议教学时长	引导讲解 60–75 分钟 + 自由动手 30 分钟
考核点	能独立装通并 `claude --version` 通过；能说出配置该写到哪一层；`codelines.py` 跑出统计结果
常见踩坑	PATH 未刷新、把个人配置误提交进 git、模糊提问导致输出不可用

本教程定位为整个 Claude Code 训练营的第 1 课地基：装好、配对、跑通。后续 Skills、MCP、Hooks 等进阶课，都依赖你在这里建立的「四层配置」心智模型。

参考来源

Quickstart — Claude Code Docs — 官方安装、登录、首会话与常用命令权威指南
Claude Code settings — Claude Code Docs — 四类作用域、优先级、settings.json 文件体系的官方定义
Claude Code settings.json 配置详解：5 层优先级、3 种文件路径 — 中文社区对配置分层、覆盖与合并规则的细致拆解
Claude Code for Beginners: Your First Project in 30 Minutes — 英文新手首项目实战，强调 CLAUDE.md、计划模式与 Git 安全网
Your first day in Claude Code — Claude Help Center — 官方 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 等场景全覆盖。

51学通信知识星球海报-扫码加入

概述