本教程带你从零完成 Claude Code 的安装、首次认证、基础配置,并用一个真实可运行的项目——命令行单位换算器(温度、长度、重量互转)——把"装好→配好→跑起来"这条主线彻底走通。读完你将:理解 Claude Code 在终端里的工作方式;独立完成 Node.js 环境检查与全局安装;用订阅账号或 API Key 完成认证;写出自己的 CLAUDE.md 与 settings.json;掌握高频斜杠命令;并能用自然语言指挥 Claude 从零生成一个带测试的小工具。适用人群:从未用过 AI 命令行编程工具、想第一次就把环境装顺、装对的开发者。
cd 进目录、会 mkdir 建文件夹即可,不需要事先会写代码——这正是让 Claude 写。Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手。它不是网页版聊天框,而是一个跑在你终端里、能真正读你的文件、改你的代码、执行命令、跑测试的智能体。你在项目目录里输入 claude 进入交互界面,用自然语言下达任务("帮我写一个温度换算工具并加测试"),它就会读写文件、运行命令、把结果交还给你确认。
它的几条核心能力,决定了入门教程的顺序:
python、pytest、git 等命令并把输出喂回给自己。CLAUDE.md 把"项目规矩"长期记住。理解了这四点,后面每一步配置你都会知道"为什么这么设"。
Claude Code 是一个 npm 全局包,先确认 Node 版本达标(≥ 18)。
打开终端,执行:
node -v
npm -v
预期结果类似:
v20.17.0
10.8.2
常见问题与解决:
command not found: node):说明没装 Node。macOS 推荐 brew install node;Windows/WSL 推荐 nvm 安装:nvm install --lts。nvm install 20 && nvm use 20,或到官网下载 LTS 安装包。npm config set registry https://registry.npmmirror.com(仅影响 npm 下载速度,不影响 Claude 本身)。一条命令全局安装:
npm install -g @anthropic-ai/claude-code
验证安装成功:
claude --version
预期输出形如 2.x.x 的版本号。看到版本号就说明可执行文件已经在 PATH 里了。
常见问题与解决:
EACCES: permission denied:权限不足。要么加 sudo(不推荐,全局包权限混乱),要么把 npm 全局目录改到用户目录下:npm config set prefix ~/.npm-global,再把 $HOME/.npm-global/bin 加进 PATH。Set-ExecutionPolicy -Scope CurrentUser RemoteSigned,或直接用 WSL。进入你打算放代码的目录,启动交互界面:
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.local.json 就是为隔离敏感配置准备的。settings.json 与 CLAUDE.md装好不等于配好。Claude Code 的配置分两块,一块管"行为开关",一块管"项目规矩"。
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"
}
}
要点:
model 指定默认模型;需要更强推理时可用 claude-opus-4-8,要省钱省速用 claude-haiku-4-5。allow 把那些"反复点同意很烦但又安全"的只读/测试命令放行,减少打断。deny 兜底拦危险操作——即便你不在场,也删不掉整盘、读不到密钥文件。你也可以在交互界面里输入 /config 用可视化方式改这些项。
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(全自动,慎用)。新手请老老实实待在默认模式。
现在把前面全部串起来,亲手造一个工具。
mkdir -p ~/projects/unit-converter && cd ~/projects/unit-converter
# 把第五步那段 CLAUDE.md 内容存成项目根目录的 CLAUDE.md
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/数值 三个参数。
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
在终端直接调用工具:
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 =====
pytest 命令找不到:本教程用的是 python -m pytest,前提是装了 pytest。Claude 会主动 pip install pytest;若你没装且离线,让它改用标准库的 unittest 重写测试。CLAUDE.md 里特意写"温度换算与线性换算区分处理"的原因——好规矩能省掉返工。把从安装到交付的链路画清楚:
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[交付可运行工具]
settings.json 的 allow,或临时 Shift+Tab 切 acceptEdits,但永远别为了省事直接上 bypassPermissions。/clear;长会话用 /compact;随时 /cost 看消耗。CLAUDE.md,而不是只口头说过一次。git init && git add -A && git commit -m init,配合 /review 让 Claude 自查,出问题就 git checkout 回退。settings.json 的 env 里配 HTTP_PROXY/HTTPS_PROXY,比每次 export 省心。-p 无头模式批量跑换算任务),形成由浅入深的课程梯度。[!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 等场景全覆盖。
