在 2026 年的 AI 编程工具里,Claude Code 是一个很特别的存在。它不是又一个写代码补全的 IDE 插件,也不是网页聊天框里的代码助手,而是 Anthropic 官方出品的命令行工具——你打开终端,跟它说”帮我写一个天气查询脚本”,它真的会把文件创建出来,把代码写好,再帮你跑通。
这一篇是【AI编程实战】系列的第一篇,我们就用 Claude Code 跑一个真实的小项目:写一个能查天气的 Python 脚本。不画大饼,不堆术语,所有命令、代码、踩坑,都来自 Anthropic 官方文档和真实使用过程。
写完这篇,你应该能用 10 分钟左右,完成从安装到跑通第一个项目。
一、为什么是 Claude Code:Anthropic 官方 CLI 的 3 个真实价值
在开始装之前,有必要先回答一个常见问题:既然已经有了 Cursor、VS Code Copilot、Claude 网页版,为什么要专门装一个命令行工具?
1.1 不是又一个 AI 聊天工具
Claude Code 的官方定位是”agentic coding tool”——能自主完成编码任务的智能体。据 Anthropic 官方文档介绍,它能”读取你的代码库、编辑文件、运行命令,并与你的开发工具集成”(来源:docs.claude.com/en/docs/claude-code/overview)。
这意味着它不只是在对话框里吐代码片段,而是能真的进入你的项目目录,创建文件、修改文件、执行命令,像一位坐在你旁边的程序员一样干活。
1.2 跟 Cursor 和 Claude Web 的本质区别
Cursor 是在 IDE 里改代码,可视化强,但要打开图形界面;Claude 网页版只能给建议,不能直接操作你的本地文件。Claude Code 走的是另一条路:终端里对话,直接在文件系统上动手。
据官方文档,Claude Code 已经在 5 个场景里落地:Terminal CLI(终端)、VS Code 扩展、JetBrains 插件、Desktop 桌面端、Web 网页版(来源:docs.claude.com/en/docs/claude-code/overview)。这一篇聚焦在 Terminal CLI,因为它是其他所有形态的”母版”——掌握 CLI,其他版本逻辑相通。
1.3 谁在用它:Anthropic 官方定位
Anthropic 官方把 Claude Code 描述为”在终端、IDE、桌面端、浏览器里都能用的 AI 编程助手”(来源:docs.claude.com/en/docs/claude-code/overview)。这意味着它不是只给程序员用的”补全工具”,而是一种”自然语言驱动开发”的新范式——你描述需求,它去实现。
💡 工具会过时,但”用自然语言驱动开发”的范式,正在成为 2026 年 AI 编程的默认姿势。
💡 看再多评测,不如跑通一个真实项目——这是学 AI 编程工具最快的方式。
💡 Claude Code 真正省下的,不是打字时间,而是查文档、研究 API、试错的时间。
二、官方文档核心概念解读
这一节专门讲清楚 Claude Code 的几个关键概念,后面用起来不迷糊。资料全部来自 Anthropic 官方文档 code.claude.com。
2.1 什么是 CLI
CLI 全称 Command Line Interface,命令行界面。简单说,就是你打开一个黑窗口,敲文字命令,电脑执行。
在 macOS 上叫”终端”(Terminal),在 Windows 上叫”PowerShell”或”命令提示符”(CMD)。Claude Code 需要运行在这样的环境里,据官方文档,Windows 原生支持需要 PowerShell 或 CMD,推荐安装 Git for Windows 以获得 Bash 工具(来源:code.claude.com/docs/en/quickstart)。
2.2 Claude Code 的工作原理
据官方文档,Claude Code 是一个”agentic coding tool”——它能:
- 读取你的代码库(像人一样浏览文件结构)
- 编辑文件(创建、修改、删除)
- 运行命令(执行 shell 命令、跑测试、装依赖)
- 集成开发工具(接 GitHub Actions、Slack、CI/CD 等)
所有这些操作,在你授权后,它会自动完成。整个交互过程就像跟一位坐在身边的程序员对话(来源:code.claude.com/docs/en/overview)。
2.3 核心能力:读写文件 / 执行命令 / 调用工具
官方把 Claude Code 的能力总结为 8 大类(来源:docs.claude.com/en/docs/claude-code/overview):
- 自动化你一直拖着没做的杂事(写测试、修 lint 错误、解决合并冲突)
- 构建功能和修复 bug(用自然语言描述需求,它会规划方案、写代码、验证)
- 创建 commit 和 pull request(直接对接 git)
- 用 MCP 连接外部工具(读 Google Drive、更新 Jira 票)
- 用 CLAUDE.md 记忆项目规则(类似项目级的”宪法”)
- 调度多个 Agent 协同(Sub-Agent 机制)
- 管道和脚本化(能接 Unix 哲学,跟其他命令拼装)
- 定时任务(早间 PR 审阅、CI 失败分析等)
2.4 支持的模型:Claude 4.5 Sonnet / Opus 4 / Haiku
据官方文档,Claude Code 默认会显示当前会话使用的模型,在终端里启动后能看到具体型号。常见的是 Claude 4.5 Sonnet(主力),Opus 4(更强但慢),Haiku 3.5(更快但简单)。具体能用哪些模型,取决于你的账号类型(来源:code.claude.com/docs/en/quickstart)。
三、5 分钟极速安装
据官方文档,Claude Code 提供了 4 种安装方式,这一节挑最常用的两种讲透。
3.1 系统要求
据官方 quickstart 文档,Claude Code 支持以下环境(来源:code.claude.com/docs/en/quickstart):
- macOS
- Linux
- Windows(通过 WSL 或 Git for Windows)
- Windows PowerShell / CMD(原生支持)
💡 Windows 用户注意:官方推荐装 WSL(Windows Subsystem for Linux),体验跟 macOS/Linux 一致;如果用原生 Windows,装 Git for Windows 可以让 Claude Code 调起 Bash 工具。
3.2 安装命令(Native Install,官方推荐)
macOS / Linux / WSL 用户,打开终端,执行:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell 用户:
irm https://claude.ai/install.ps1 | iex
Windows CMD 用户:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
据官方说明,native install 安装方式会在后台自动更新,保持最新版本(来源:code.claude.com/docs/en/quickstart)。
3.3 备选安装方式
如果你是 macOS 用户且装了 Homebrew:
brew install --cask claude-code
据官方说明,Homebrew 提供两个 cask:claude-code 跟稳定版(约晚一周)、claude-code@latest 跟最新版(发布即更新)。Homebrew 安装不会自动更新,需要手动 brew upgrade(来源:code.claude.com/docs/en/quickstart)。
3.4 验证安装
装完后,跑这个命令看版本:
claude --version
能输出版本号(比如 2.x.x),就说明装好了。
3.5 登录账号
首次使用需要登录:
claude
据官方文档,首次运行会提示你在浏览器里登录。支持的账号类型有 4 种(来源:code.claude.com/docs/en/quickstart):
- Claude Pro / Max / Team / Enterprise 订阅(推荐,适合个人开发者)
- Claude Console(API 访问,按 token 计费)
- Amazon Bedrock / Google Vertex AI / Microsoft Foundry(企业云服务)
登录一次后会保存凭证,后续不用再登录。
3.6 国内访问说明
这是绕不开的现实问题:Anthropic 的服务在国内访问需要稳定的网络环境,具体能不能用、延迟多少,因人而异。
如果安装脚本下载慢或登录页打不开,通常需要配置代理。官方文档没有针对国内网络做专门说明,本节也不展开具体方案——请根据自身情况,选择合适的网络环境。
四、实战项目:天气查询 API(核心教程)
理论讲完,直接动手。我们用 Claude Code 写一个能查天气的 Python 脚本,用到的天气 API 是公开免费的 wttr.in,不需要注册 key。
4.1 项目需求拆解
我们的目标:
- 用户在终端里运行 `python weather.py 城市名`
- 脚本返回这个城市当前的天气状况
- 数据来源:wttr.in(免费,无需 key,支持命令行直接调用)
4.2 第一步:初始化项目目录
打开终端,新建一个项目文件夹:
mkdir weather-cli
cd weather-cli
4.3 第二步:启动 Claude Code
在项目目录下启动:
claude
第一次会看到欢迎界面,输入 /help 能看到所有可用命令。
4.4 第三步:用自然语言让 Claude Code 写代码
在 Claude Code 的提示符后,直接输入:
写一个 Python 脚本 weather.py,接收命令行参数作为城市名,调用 wttr.in 的 API(URL 格式:https://wttr.in/城市名?format=j1)获取 JSON 格式的天气数据,然后格式化输出当前的温度、天气状况、湿度、风速。
Claude Code 会:
1. 看看当前目录里有什么文件
2. 规划怎么实现
3. 给你看一份方案,问你是否同意
4. 创建 weather.py 文件
5. 等待你下一步指令
据官方 quickstart 文档描述,Claude Code 在修改文件前会请求授权,你可以逐次批准,也可以开启”Accept all”模式一次授权(来源:code.claude.com/docs/en/quickstart)。
4.5 第四步:让 Claude Code 跑通测试
代码写好后,直接跟 Claude Code 说:
跑一下试试,用 Beijing 作为城市名
Claude Code 会执行 python weather.py Beijing,并把输出贴回来。
4.6 第五步:添加中文支持和错误处理
发现输出格式有点丑,继续跟它说:
1. 城市名支持中文(比如 "北京")
2. 如果用户没输入城市名,提示用法
3. 如果城市名拼错,给出友好提示
Claude Code 会修改 weather.py,加 try/except,加 argparse,加默认城市。
4.7 完整代码参考
下面是预期生成的代码框架(实际可能略有差异,Claude Code 会按你给的指令调整):
#!/usr/bin/env python3
"""天气查询命令行工具 - 数据源:wttr.in"""
import sys
import json
import argparse
import urllib.request
import urllib.error
def fetch_weather(city: str) -> dict:
"""从 wttr.in 获取天气数据"""
url = f"https://wttr.in/{city}?format=j1"
with urllib.request.urlopen(url, timeout=10) as resp:
return json.loads(resp.read().decode("utf-8"))
def parse_weather(data: dict) -> dict:
"""解析 JSON,提取关键信息"""
current = data["current_condition"][0]
return {
"温度": current["temp_C"] + "°C",
"体感": current["FeelsLikeC"] + "°C",
"天气": current["weatherDesc"][0]["value"],
"湿度": current["humidity"] + "%",
"风速": current["windspeedKmph"] + " km/h",
}
def main():
parser = argparse.ArgumentParser(description="查询指定城市的当前天气")
parser.add_argument("city", nargs="?", default="Beijing", help="城市名,中英文均可")
args = parser.parse_args()
try:
data = fetch_weather(args.city)
weather = parse_weather(data)
print(f"\n📍 {args.city} 当前天气")
print("─" * 30)
for k, v in weather.items():
print(f" {k}: {v}")
print()
except urllib.error.HTTPError:
print(f"❌ 找不到城市: {args.city},请检查拼写")
sys.exit(1)
except Exception as e:
print(f"❌ 查询失败: {e}")
sys.exit(1)
if __name__ == "__main__":
main()
把这个脚本保存为 weather.py,在终端运行:
python weather.py Beijing
python weather.py 北京
python weather.py Shanghai
就能看到格式化输出的天气信息。整个项目从零到跑通,大概 10 分钟。
💡 跟传统开发比,Claude Code 让你不用查 wttr.in 的 API 文档,不用研究 JSON 字段名,不用写 argparse——用自然语言描述需求,它帮你搞定。
💡 跟 AI 协作的最高境界,不是问它”怎么写”,而是描述”我要什么效果”——目标导向,而不是步骤导向。
💡 跑通一个小项目,比读十篇教程更有用——这是学编程工具的”最小可执行单元”。
💡 给 AI 的指令越具体,结果越可控——模糊的需求会换来模糊的代码,这是常识,也是真理。
五、进阶用法:3 个真实提效技巧
基础项目跑通后,这几个进阶用法能让 Claude Code 真正融入日常工作流。
5.1 CLAUDE.md:让 AI 记住你的项目规则
据官方文档,CLAUDE.md 是一个放在项目根目录的 Markdown 文件,Claude Code 在每次会话开始时会自动读取它(来源:docs.claude.com/en/docs/claude-code/overview)。
你可以在 CLAUDE.md 里写:
# 项目规则
- 用 Python 3.11+ 语法
- 优先用标准库,避免引入第三方依赖
- 函数必须有 docstring
- 错误处理用 try/except,不用裸 except
这样,Claude Code 在写代码时会自动遵守这些规则,不用每次重复说。
官方还提到了一个”auto memory”机制——Claude 在工作中会自动保存学到的项目信息(比如构建命令、调试心得),跨会话保留(来源:docs.claude.com/en/docs/claude-code/overview)。
5.2 斜杠命令:/init /clear /cost
据官方文档,Claude Code 提供了大量斜杠命令(来源:code.claude.com/docs/en/quickstart):
- `/help`:显示所有可用命令
- `/clear`:清空当前对话历史
- `/init`:在当前目录自动生成 CLAUDE.md
- `/cost`:查看本次会话的 token 消耗和费用
- `/login`:重新登录账号
- `/resume`:恢复之前的对话
最常用的是 /init——第一次进入新项目时,跑一下,它会自动扫描项目结构,生成一份 CLAUDE.md,把你可能要反复说的项目背景写好。
5.3 工具权限管理:白名单机制
据官方文档,Claude Code 在执行敏感操作前(比如写文件、执行 shell 命令)会请求用户授权(来源:code.claude.com/docs/en/quickstart)。
💡 安全和效率永远是天平的两端——Claude Code 的权限设计,是为了让你能动态调整。
你可以:
- 逐次批准:每一步都点确认,适合新项目熟悉阶段
- Accept all:一次授权整个会话,适合信任的项目和明确的开发任务
- 自定义白名单:在 settings 里配置哪些命令可以自动执行(比如 `npm test`)
官方推荐的做法是”Shift+Tab 循环切换权限模式”,在安全和效率之间找平衡(来源:code.claude.com/docs/en/quickstart)。
六、6 个真实踩坑案例
教程写得再漂亮,实际用的时候总会有意外。这一节是 6 个真实常见的坑,提前打个预防针。
6.1 坑 1:安装脚本下载超时
症状:执行 curl -fsSL https://claude.ai/install.sh | bash 时卡住,半天没反应。
原因:网络环境问题。claude.ai 在部分地区访问不稳定。
解决:先单独下载脚本看能不能拿到:
curl -fsSL https://claude.ai/install.sh -o install.sh
cat install.sh # 先看看内容,确认是合法的
bash install.sh
如果下载本身就不行,只能换网络环境再试。
6.2 坑 2:登录后提示”无法访问 API”
症状:登录成功,但发任何指令都报错 “API Error” 或 “Authentication failed”。
原因:账号类型和模型权限不匹配。某些账号只支持特定模型。
解决:在 Claude Code 里输入 /status 查看当前账号状态;如果用 Pro 订阅,确认订阅处于活跃状态;如果用 Console API,确认余额充足。
6.3 坑 3:Windows PowerShell 报错 “irm 不是内部命令”
症状:在 Windows CMD 里执行了 PowerShell 命令 irm ... | iex,提示 “‘irm’ is not recognized”。
原因:CMD 和 PowerShell 是两个不同的 shell,命令不通用。据官方文档,如果提示符是 C:\> 是 CMD,提示符是 PS C:\> 才是 PowerShell(来源:code.claude.com/docs/en/quickstart)。
解决:在 PowerShell 里重试,或者用 CMD 版本的命令:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
6.4 坑 4:wttr.in 偶尔返回 503
症状:跑 weather.py 时,偶尔报 “Service Unavailable”。
原因:wttr.in 是免费服务,高峰期可能短暂不可用。
解决:在代码里加重试机制,或者提示用户稍后重试。这是用第三方免费 API 的常态,不是 Claude Code 的问题。
6.5 坑 5:长任务上下文被截断
症状:跑一个长任务,做到一半 Claude Code “忘了”之前的需求。
原因:对话历史超过 token 上限,旧消息被截断。
解决:用 /clear 在合适节点清空历史,或者在 CLAUDE.md 里把核心需求写清楚——这样即使历史被清,关键信息还在项目级记忆里。
💡 上下文不是免费的——AI 编程工具的 token 也是成本,会”清缓存”是基本功。
6.6 坑 6:Claude Code 改了不该改的文件
症状:让 Claude Code 修 bug,它顺手把不相关的代码也改了。
原因:Claude Code 的 agentic 能力意味着它会自主判断哪些文件相关,如果指令不够具体,可能”扩大打击面”。
解决:指令要具体——”只改 src/auth.py 里的 login 函数,不要动其他文件”。还可以用 git 提前 commit 一份,出问题能回滚。
七、举一反三:3 个可改造的扩展项目
天气查询只是入门。掌握了这个套路,你可以改造成任何你想要的命令行工具。
7.1 改成股票查询(换 API)
把 wttr.in 换成股票 API(比如 Yahoo Finance 的 query1.finance.yahoo.com),同样套路:
写一个 stock.py,接收股票代码作为参数,调用 Yahoo Finance 的 API,返回当前股价、涨跌幅、市值
7.2 改成 IP 归属地查询
用 ip-api.com 这个免费 API:
写一个 ipinfo.py,接收 IP 地址作为参数,调用 ip-api.com 返回国家、城市、运营商
7.3 改成 GitHub 仓库统计
用 GitHub 官方 API(无需 key,有限流):
写一个 ghinfo.py,接收 GitHub 用户名作为参数,调用 api.github.com/users/xxx,返回 Star 总数、Followers、最受欢迎的 3 个仓库
这三个项目都遵循同样的模式:命令行参数 → HTTP 请求 → JSON 解析 → 格式化输出。把 weather.py 改一改,就能做出自己顺手的工具集。
八、常见问题 Q&A
8.1 Claude Code 和 Cursor 怎么选?
据官方文档,Claude Code 在终端、IDE、桌面端、浏览器都有入口,在 VS Code 和 Cursor 上都有官方扩展(来源:code.claude.com/docs/en/overview)。所以严格说不是”二选一”,可以组合用:日常写代码用 Cursor,跑批处理、CI/CD、纯命令行任务用 Claude Code CLI。
8.2 免费用户能用吗?
据官方文档,Claude Code 需要 Claude 订阅(Pro / Max / Team / Enterprise)或 Claude Console 账号(API 按量付费),没有永久免费层(来源:code.claude.com/docs/en/quickstart)。Pro 订阅每月有额度限制,Console 账号按 token 用量计费。
8.3 中文支持怎么样?
Claude 模型本身对中文支持良好,无论是理解中文需求还是用中文写注释、错误提示,都没问题。代码里的标识符建议用英文(行业惯例),注释和提示信息可以用中文。
8.4 数据安全吗?代码会上传吗?
据官方文档,Claude Code 在 Anthropic Console 账号下,代码会发送到 Anthropic 的服务器进行处理(这是 API 类工具的通用做法)。如果你有严格的代码保密要求,可以使用企业版(Enterprise),数据隔离更严格。或者使用 Amazon Bedrock / Google Vertex AI 等第三方云服务,数据走你自己的云账号(来源:code.claude.com/docs/en/quickstart)。
8.5 跟 VSCode Copilot 冲突吗?
不冲突,可以在同一台机器上同时装。但据官方文档,Claude Code 在 VS Code 里也有自己的扩展(来源:docs.claude.com/en/docs/claude-code/overview),如果两个都用,功能会有重叠。建议选一个主力,另一个当辅助。
8.6 能在 Windows 上用吗?
能。据官方文档,Windows 原生支持 PowerShell 和 CMD,推荐装 Git for Windows 以获得 Bash 工具(来源:code.claude.com/docs/en/quickstart)。如果想要最佳体验,官方推荐用 WSL(Windows Subsystem for Linux),跑起来跟 macOS/Linux 一致。
8.7 怎么升级到最新版本?
据官方文档,native install 安装方式会在后台自动更新;Homebrew 安装需要手动 brew upgrade claude-code;WinGet 安装需要 winget upgrade Anthropic.ClaudeCode(来源:code.claude.com/docs/en/quickstart)。
也可以手动指定版本:
claude install stable # 稳定版
claude install latest # 最新版
claude install 2.1.118 # 指定版本号
8.8 国内网络能用吗?
官方文档没有针对国内网络做专门说明。实际使用需要稳定的网络环境能访问 anthropic.com 和 claude.ai,具体网络方案不在本文讨论范围。
九、官网与下载链接
- 官方文档:https://code.claude.com/docs/en/overview
- Quickstart 快速入门:https://code.claude.com/docs/en/quickstart
- CLI 命令参考:https://code.claude.com/docs/en/cli-reference
- Anthropic Console:https://console.anthropic.com/
- 定价页面:https://claude.com/pricing
安装命令汇总:
| 平台 | 命令 | |
|---|---|---|
| macOS / Linux / WSL | `curl -fsSL https://claude.ai/install.sh \ | bash` |
| Windows PowerShell | `irm https://claude.ai/install.ps1 \ | iex` |
| Windows CMD | `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` | |
| Homebrew(macOS) | `brew install –cask claude-code` | |
| WinGet(Windows) | `winget install Anthropic.ClaudeCode` |
账号类型与价格(据官方定价页面):
| 账号类型 | 计费方式 | 适用人群 |
|---|---|---|
| Claude Pro | 月度订阅 | 个人轻度使用 |
| Claude Max | 月度订阅(更高额度) | 个人重度使用 |
| Claude Team | 月度订阅(按席位) | 小团队 |
| Claude Enterprise | 销售联系 | 大型企业 |
| Claude Console | 按 token 用量 | 开发者、API 调用 |
十、行动建议 + 互动话题
10.1 三步上手计划
如果你是第一次接触 Claude Code,建议按这个顺序走:
第 1 天(15 分钟):装好,跑 claude --version 验证,在示例项目里玩一下 /init、/clear、/cost 三个命令。
第 3 天(30 分钟):按本教程跑通 weather.py,体验”自然语言 → 代码 → 跑通”完整链路。
第 7 天(1 小时):在你自己正在做的真实项目里,用 Claude Code 写一个小功能(比如写测试、修 bug、加日志),感受真实工作流。
10.2 互动话题
这一篇是【AI编程实战】系列的开篇,后面还有 4 篇(Cursor、Coze、Dify、Codex CLI)。你日常用得最多的是哪个 AI 编程工具?在终端里跟 AI 对话,跟图形界面比,你觉得哪个更顺手?
欢迎在评论区说说你的体验,下一篇我会根据大家反馈决定先写哪一篇。
参考资料:
- Anthropic 官方文档 – Overview:https://code.claude.com/docs/en/overview
- Anthropic 官方文档 – Quickstart:https://code.claude.com/docs/en/quickstart
- Anthropic 官方文档 – CLI Reference:https://code.claude.com/docs/en/cli-reference
- wttr.in 天气 API:https://github.com/chubin/wttr.in(公开免费 API,无需 key)
- Claude 订阅定价:https://claude.com/pricing
我要评论