首页 › tutorials › 零基础装通Claude Code造首个换算器

概述

本教程带你从零完成 Claude Code 的安装、首次认证、基础配置,并用一个真实可运行的项目——命令行单位换算器(温度、长度、重量互转)——把"装好→配好→跑起来"这条主线彻底走通。读完你将:理解 Claude Code 在终端里的工作方式;独立完成 Node.js 环境检查与全局安装;用订阅账号或 API Key 完成认证;写出自己的 CLAUDE.md 与 settings.json;掌握高频斜杠命令;并能用自然语言指挥 Claude 从零生成一个带测试的小工具。适用人群:从未用过 AI 命令行编程工具、想第一次就把环境装顺、装对的开发者。

前置条件


第一步:先搞清楚 Claude Code 是什么

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手。它不是网页版聊天框,而是一个跑在你终端里、能真正读你的文件、改你的代码、执行命令、跑测试的智能体。你在项目目录里输入 claude 进入交互界面,用自然语言下达任务("帮我写一个温度换算工具并加测试"),它就会读写文件、运行命令、把结果交还给你确认。

它的几条核心能力,决定了入门教程的顺序:

理解了这四点,后面每一步配置你都会知道"为什么这么设"。

第二步:准备 Node.js 环境

Claude Code 是一个 npm 全局包,先确认 Node 版本达标(≥ 18)。

打开终端,执行:

node -v
npm -v

预期结果类似:

v20.17.0
10.8.2

常见问题与解决:

第三步:安装 Claude Code

一条命令全局安装:

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

验证安装成功:

claude --version

预期输出形如 2.x.x 的版本号。看到版本号就说明可执行文件已经在 PATH 里了。

常见问题与解决:

第四步:首次启动与认证

进入你打算放代码的目录,启动交互界面:

mkdir ~/projects && cd ~/projects
claude

第一次启动会要求你认证,有两条路:

路线 A:订阅账号登录(Pro / Max,推荐新手)

选择浏览器登录后,终端会显示一个网址和一串验证码,自动打开浏览器,确认后回到终端,提示已登录。此后在订阅额度内使用,无需管 API Key。

路线 B:API Key 计费

到 Anthropic Console 创建一把 Key,然后两种方式二选一:

# 方式一:写进 shell 配置(推荐,长期生效)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc   # bash 用户改 ~/.bashrc
source ~/.zshrc

# 方式二:仅在当前会话临时设置
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

再运行 claude 即可。

常见问题与解决:

第五步:配置 settings.json 与 CLAUDE.md

装好不等于配好。Claude Code 的配置分两块,一块管"行为开关",一块管"项目规矩"。

5.1 settings.json:行为与权限

Claude Code 按优先级读取三层配置:

文件 作用域 是否进版本库
~/.claude/settings.json 全局,所有项目生效 否(个人偏好)
项目/.claude/settings.json 团队共享 是
项目/.claude/settings.local.json 本机个人覆盖 否(含密钥/本机路径)

一个稳妥的入门全局配置示例 ~/.claude/settings.json:

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(python:*)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./.env)",
      "Read(./**/*.pem)"
    ]
  },
  "env": {
    "HTTP_PROXY": "http://127.0.0.1:7890"
  }
}

要点:

你也可以在交互界面里输入 /config 用可视化方式改这些项。

5.2 CLAUDE.md:项目记忆

CLAUDE.md 是给 Claude 看的"项目说明书"。最省事的生成方式:在项目根目录运行:

claude
> /init

Claude 会扫描项目结构、自动生成一份 CLAUDE.md 初稿,你再手动润色。对本教程的换算器项目,目标 CLAUDE.md 长这样:

# 项目:命令行单位换算器

## 目标
一个零依赖的 Python 命令行工具,支持温度、长度、重量三类单位互转。

## 运行方式
- 运行:`python converter.py --from C --to F 100`
- 测试:`python -m pytest test_converter.py -v`

## 代码规范
- 只用 Python 标准库,不引入第三方依赖。
- 所有公共函数写中文 docstring。
- 数值换算保留 4 位小数。
- 温度换算与线性换算区分处理。

## 目录结构
- converter.py:核心逻辑与 CLI 入口
- test_converter.py:单元测试

CLAUDE.md 的记忆是分层的:企业级 > 用户级(~/.claude/CLAUDE.md)> 项目根目录 > 子目录。越靠近文件,优先级越高,所以你可以在不同子目录放不同规矩。

第六步:高频斜杠命令速览

进入交互界面后,这些命令是日常:

命令 作用
/help 查看全部命令
/init 扫描项目并生成 CLAUDE.md
/config 可视化修改设置
/model 切换 Opus / Sonnet / Haiku
/clear 清空当前对话上下文(换任务前必用)
/compact 压缩上下文,长会话省额度
/cost 看本次会话花了多少 token / 钱
/review 让 Claude 审一遍当前改动
/agents 管理子代理
/mcp 管理 MCP 外部工具

另外有四个权限模式值得关注,按"放手程度"递增:默认(每次确认)→ acceptEdits(自动接受文件编辑)→ Plan 模式(只规划不动手,按 Shift+Tab 切换)→ bypassPermissions(全自动,慎用)。新手请老老实实待在默认模式。

第七步:第一个项目——命令行单位换算器(实战)

现在把前面全部串起来,亲手造一个工具。

7.1 建项目骨架

mkdir -p ~/projects/unit-converter && cd ~/projects/unit-converter
# 把第五步那段 CLAUDE.md 内容存成项目根目录的 CLAUDE.md
claude

7.2 给 Claude 的提示词

进入交互界面后,先建任务清单,再让它动手。把下面这段直接发给它:

请阅读 CLAUDE.md,然后帮我实现这个命令行单位换算器,分两步:

1. 先用 TodoWrite 列出任务清单(实现核心库、实现 CLI、写测试、跑测试)。
2. 按清单逐步实现 converter.py 与 test_converter.py,每写完一块就用
   python -m pytest 跑一遍测试,全部通过再交付。

要求:
- 温度:C(摄氏) ↔ F(华氏) ↔ K(开尔文)
- 长度:m / km / cm / mile / foot / inch
- 重量:g / kg / t / lb / oz
- 命令行用 argparse,支持 --from/--to/数值 三个参数。

7.3 预期结果

Claude 会先生成 converter.py,核心逻辑大致如下(它会按你的 CLAUDE.md 规范来写):

import argparse

# 各单位到基准单位的换算因子(温度单独处理)
LENGTH_TO_METER = {
    "m": 1.0, "km": 1000.0, "cm": 0.01,
    "mile": 1609.344, "foot": 0.3048, "inch": 0.0254,
}
WEIGHT_TO_GRAM = {
    "g": 1.0, "kg": 1000.0, "t": 1_000_000.0,
    "lb": 453.59237, "oz": 28.349523125,
}

def convert_length(value, src, dst):
    """把 value 从 src 长度单位换算到 dst,保留 4 位小数。"""
    if src not in LENGTH_TO_METER or dst not in LENGTH_TO_METER:
        raise ValueError(f"不支持的长度单位: {src} 或 {dst}")
    meters = value * LENGTH_TO_METER[src]
    return round(meters / LENGTH_TO_METER[dst], 4)

def convert_weight(value, src, dst):
    """把 value 从 src 重量单位换算到 dst,保留 4 位小数。"""
    if src not in WEIGHT_TO_GRAM or dst not in WEIGHT_TO_GRAM:
        raise ValueError(f"不支持的重量单位: {src} 或 {dst}")
    grams = value * WEIGHT_TO_GRAM[src]
    return round(grams / WEIGHT_TO_GRAM[dst], 4)

def convert_temperature(value, src, dst):
    """温度换算:在摄氏、华氏、开尔文之间互转。"""
    table = {"C", "F", "K"}
    if src not in table or dst not in table:
        raise ValueError(f"不支持的温度单位: {src} 或 {dst}")
    # 先统一到摄氏
    if src == "F":
        c = (value - 32) * 5 / 9
    elif src == "K":
        c = value - 273.15
    else:
        c = value
    # 再从摄氏到目标
    if dst == "F":
        return round(c * 9 / 5 + 32, 4)
    if dst == "K":
        return round(c + 273.15, 4)
    return round(c, 4)

def main():
    p = argparse.ArgumentParser(description="命令行单位换算器")
    p.add_argument("--from", dest="src", required=True, help="源单位")
    p.add_argument("--to", dest="dst", required=True, help="目标单位")
    p.add_argument("value", type=float, help="待换算的数值")
    args = p.parse_args()

    src, dst = args.src, args.dst
    if src in LENGTH_TO_METER and dst in LENGTH_TO_METER:
        result = convert_length(args.value, src, dst)
    elif src in WEIGHT_TO_GRAM and dst in WEIGHT_TO_GRAM:
        result = convert_weight(args.value, src, dst)
    else:
        result = convert_temperature(args.value, src, dst)
    print(f"{args.value} {src} = {result} {dst}")

if __name__ == "__main__":
    main()

对应的 test_converter.py:

from converter import convert_temperature, convert_length, convert_weight

def test_temperature():
    assert convert_temperature(100, "C", "F") == 212.0
    assert convert_temperature(0, "C", "K") == 273.15
    assert convert_temperature(32, "F", "C") == 0.0

def test_length():
    assert convert_length(1, "km", "m") == 1000.0
    assert convert_length(1, "mile", "km") == 1.6093

def test_weight():
    assert convert_weight(1, "kg", "g") == 1000.0
    assert convert_weight(1, "lb", "kg") == 0.4536

7.4 运行与测试

在终端直接调用工具:

python converter.py --from C --to F 100
# 100 C = 212.0 F

python converter.py --from km --to mile 10
# 10 km = 6.2137 mile

python converter.py --from lb --to kg 150
# 150 lb = 68.0388 kg

跑测试(Claude 在生成过程中会自己执行这一步并把结果给你):

python -m pytest test_converter.py -v

预期全部通过:

test_converter.py::test_temperature PASSED
test_converter.py::test_length PASSED
test_converter.py::test_weight PASSED
===== 3 passed in 0.02s =====

7.5 常见问题与解决

整体工作流

把从安装到交付的链路画清楚:

flowchart TD
    A[检查 Node.js ≥ 18] --> B[npm 全局安装 Claude Code]
    B --> C[claude 首次启动]
    C --> D{选择认证方式}
    D -->|Pro/Max 订阅| E[浏览器 OAuth 登录]
    D -->|API Key| F[设置 ANTHROPIC_API_KEY]
    E --> G[写 settings.json 权限与模型]
    F --> G
    G --> H[cd 进入项目 + claude]
    H --> I[/init 生成 CLAUDE.md 并润色]
    I --> J[自然语言下达任务]
    J --> K[Claude 读写文件/跑命令]
    K --> L{你确认改动}
    L -->|确认| M[跑测试通过]
    L -->|拒绝/修改| J
    M --> N[交付可运行工具]

常见坑与排错清单

  1. 每次都要点同意很烦:把高频安全命令加进 settings.json 的 allow,或临时 Shift+Tab 切 acceptEdits,但永远别为了省事直接上 bypassPermissions。
  2. 上下文越聊越贵:换任务前 /clear;长会话用 /compact;随时 /cost 看消耗。
  3. Claude 忘了项目规矩:确认规矩写进了项目根目录的 CLAUDE.md,而不是只口头说过一次。
  4. 改动乱、不好回滚:动手前先 git init && git add -A && git commit -m init,配合 /review 让 Claude 自查,出问题就 git checkout 回退。
  5. 网络不稳定:在 settings.json 的 env 里配 HTTP_PROXY/HTTPS_PROXY,比每次 export 省心。
  6. Windows 路径/换行问题:直接用 WSL2,能避开 90% 的环境坑。

训练营适用性评估

延伸阅读

参考来源

  1. Claude Code 官方文档 Overview — Anthropic 官方对安装、认证、配置、工作流的权威说明。
  2. @anthropic-ai/claude-code npm 包 — 全局安装命令与版本信息来源。
  3. 2026 完整版 Claude Code 入门教程(CSDN) — 中文社区从零安装到核心命令的实战教程。
  4. Claude Code CLI 配置 2026:5 分钟快速上手 — 面向工程师的快速上手与 settings 配置实践。
  5. Claude Code 2026 完整使用指南(SoloSoft) — 覆盖权限模式、记忆系统与多代理架构的深度解析。

[!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学通信知识星球海报-扫码加入