Claude Code 完整上手教程：从安装配置到高效编程实战

最近总有人问我Claude Code 到底怎么开始用装完以后打开终端面对一个光标完全不知道该说什么。作为每天靠它写代码、改 bug 的人我想把这份完整的上手笔记写出来。这篇文章没有什么高深的理论全部是我自己安装、配置、踩坑之后的真实流程。目标读者很明确一是刚听说 Claude Code、不知道自己需不需要的人二是已经装了但只会“你好”“帮我写个排序”的人。看完以后你应该能独立完成安装、登录、接入 VS Code、切换模型、配置常用技能并且知道报错时先去查哪里。1. 先别急着装先把 Claude Code 定位搞清楚很多人第一步就搞错了以为 Claude Code 是类似“Claude 网页版”的套壳客户端或者以为它只是个 IDE 插件。其实它是一个跑在终端里的编程智能体核心不是“聊天”而是“干活”。1.1 Claude Code 是“跑在终端里的编程员工”Claude Code 是 Anthropic 推出的命令行工具CLI安装之后你在终端里输入claude就会进入一个交互式命令行。你可以用自然语言给它下指令比如“帮我看看这个项目的测试为什么失败”“把这段重复代码抽取成公共函数”“给所有接口加上超时重试”。它和普通聊天机器人的最大区别在于它能直接读写你当前项目里的文件能执行 Shell 命令能运行测试能根据命令输出判断下一步该做什么。换句话说它不是一个只会“建议”的助手而是一个能真正动手改代码的执行者。这也意味着你要给它一定的“信任边界”。我在第一次使用时就踩过坑让它清理无用文件它很积极地把一个看起来没用的配置文件删了结果那是一个旧功能还在依赖的配置。所以后来我养成了习惯——凡是涉及删除、批量移动文件的操作我会先在指令里明确写“先列出计划不要执行等我确认”。1.2 它和网页版 Claude、ChatGPT 到底有什么区别简单对比一下网页版 Claude适合问答、写单文件、改一小段代码。优点是零安装、界面友好但它看不到你本地项目的完整结构也不能主动执行命令。ChatGPT / Codex同为 AI 对话工具但 ChatGPT 更偏向通用问答Codex 虽然也是终端 Agent但生态、模型选择、配置方式都不一样后面会专门讲。Claude Code驻扎在本地终端能读文件、改文件、跑命令还支持 MCP、Skills 这类扩展机制。它更像是“在项目里工作的同事”而不是“隔着屏幕给你出主意的人”。所以如果你的场景只是“帮我写个正则”网页版完全够用但如果你想让 AI 完整处理一个本地仓库里的任务比如跨文件重构、排查 CI 报错、批量补充测试用例那就应该用 Claude Code。1.3 到底适合谁来用不适合谁我说点得罪人的大实话真想用好 Claude Code你得具备一点终端基础。至少要会打开命令行、知道cd切目录、能看懂简单的报错。倒不是说你必须是资深程序员但完全不懂命令行的话光安装这一步就能劝退。适合用的人有几类前后端开发、测试、运维需要高频改代码的人写脚本、做自动化小工具的爱好者需要快速验证想法、但是手写代码比较慢的“半技术”人群团队内部需要统一代码规范、重复性重构很多的技术负责人。不适合的人也很明确害怕命令行、不愿意学任何环境配置、希望“一键双击就能用”的朋友。这类朋友我建议先装 VS Code 插件版通过图形界面降低门槛等用熟了再回到终端。2. 安装和初始化一次过关这一节我尽量把每一步都写清楚。很多新手卡在安装并不是不会复制粘贴而是环境本身有问题或者登录时遇到了奇奇怪怪的报错。2.1 环境要求与账号准备Claude Code 的核心安装方式是 npm 包所以你的电脑上必须要有 Node.js 和 npm。建议 Node.js 版本在 18 以上我用的是 20 LTS长期稳定版本问题最少。检查方式是在终端输入node -v npm -v如果没装去 Node.js 官网下载 LTS 版本即可。Windows 用户建议顺手装一个 Git Bash 或者 Windows Terminal后续体验会好很多。账号方面你至少需要满足下面两种条件之一一个 Claude 订阅账号Pro / Max 等登录时走 OAuth 授权一个 Anthropic API Key按 token 用量付费。如果你只是个人日常用订阅账号通常更划算如果是做自动化、批量跑任务API Key 会更灵活。但不管哪种都需要在首次登录时完成授权。2.2 安装命令和镜像源问题安装命令非常简单在终端执行npm install -g anthropic-ai/claude-code装完以后验证版本claude --version如果安装过程非常慢或者卡在npm下载不动多半是网络到默认 npm 源不够顺畅。你可以换成国内镜像源再试npm config set registry https://registry.npmmirror.com设置完成后再重新执行安装命令。这里有个注意点不要为了图省事直接跳过-g全局安装否则claude命令不会进入系统 PATH后面你会在“找不到命令”这件事上浪费很多时间。2.3 首次登录的正确姿势在项目目录下打开终端输入claude首次使用会看到登录引导通常是给你一个链接让浏览器打开并完成授权。订阅用户建议选择 OAuth 登录复制终端里提供的授权码在浏览器页面粘贴后确认再回到终端基本就能进入正式的交互界面。登录成功后推荐先敲几个命令感受一下/help查看所有可用命令/status查看当前会话状态和模型信息/model查看或者切换模型。第一次进入时Claude Code 可能会提示你要不要生成 CLAUDE.md 项目说明文件。我建议选“要”这东西后面有大用它可以记录项目结构、构建命令、代码风格相当于给 AI 一个“项目入职手册”。2.4 PowerShell 安装报错的原因和解决办法Windows 用户最容易在 PowerShell 里栽跟头常见的报错有两类。第一类是 npm 安装时提示权限不足比如Error: EACCES: permission denied。原因很可能是你的 Node.js 装在系统盘全局包需要写入受保护目录。解决办法有两个一是右键以管理员身份运行 PowerShell然后再执行安装命令二是我更推荐的——用 nvm 管理 Node.js把全局安装目录放到用户目录下避免权限问题。第二类是安装成功后执行claude却提示“不是内部或外部命令”。这基本就是 npm 全局 bin 目录不在 PATH 里。你可以先执行npm config get prefix看看输出的路径是什么再手动把%APPDATA%\npmWindows或那个路径下的 bin 目录加到系统环境变量 PATH 中。试过之后只要重新打开终端claude基本就能识别了。注意遇到 PowerShell 执行策略阻止脚本的情况不要一上来就Set-ExecutionPolicy Unrestricted。先试试对当前用户设置Set-ExecutionPolicy RemoteSigned -Scope CurrentUser更安全也足够日常使用。3. 把它装进 VS Code / IDEA别在终端裸奔了很多人不习惯在黑乎乎的终端里操作更喜欢在编辑器里看着代码改动。没问题Claude Code 并不是只能活在终端里的“苦行僧”工具。3.1 VS Code 官方扩展配置Claude Code 官方提供了 VS Code 扩展。你直接在 VS Code 的扩展市场里搜索“Claude Code”看到 Anthropic 官方出品的那一个点击安装即可。安装完成后左侧边栏会多出一个 Claude Code 面板。在这个面板里你能直接打开一个新会话选择当前工作区目录然后开始提问。和终端版相比编辑器集成的好处很明显代码改动会以 Diff 形式呈现你能清楚地看到 AI 改了什么点击具体文件可以直接跳转到对应位置简化了“上下文”概念它天然知道当前打开的项目目录。就算你装了扩展claude命令行依然可以正常使用两者互不冲突。我自己的习惯是简单任务直接在终端快速跑涉及多处修改的重构任务放到 VS Code 面板里方便 review。3.2 用 cc switch 工具自由切换模型供应商Claude Code 默认使用 Anthropic 官方模型但这不代表你只能用它。因为它底层通过环境变量来控制模型接口地址比如ANTHROPIC_BASE_URL、ANTHROPIC_MODEL、ANTHROPIC_AUTH_TOKEN所以理论上它可以接任何兼容 Anthropic API 格式的服务。手动改环境变量很麻烦这时就轮到 cc switch 出场了。它是一个开源工具专门用来快速切换 Claude Code 的供应商配置。你可以提前配置好几套 profile比如官方 Claude SonnetDeepSeek 兼容接口GLM 兼容接口本地 Ollama 模型。安装方式通常是npm install -g cc-switch或者去它的 GitHub Release 页下载桌面版图形工具。安装后打开添加 provider填写 Base URL、模型名称、API Key保存后点击切换它会自动重写 Claude Code 的配置文件或环境变量。下次启动claude时用的就是你选中的那一套配置。我个人最喜欢这个工具的点在于它把“切换模型”变成了一次点击的事。比如我白天用 DeepSeek 跑一些成本敏感的重复任务晚上需要深度重构时切回官方 Claude不用再背一串环境变量。3.3 接入 Ollama 本地大模型的完整流程如果你有隐私要求或者想完全离线使用可以接本地的 Ollama 模型。Ollama 是一个本地大模型运行工具装好后可以拉取qwen2.5-coder、llama3等模型默认监听端口是11434。但有一点必须提前说清楚Claude Code 原生并不直接吃 OpenAI 格式接口它期望的是 Anthropic Messages API。所以最省事的方案是使用 cc switch 里预设的 Ollama 支持它会帮你处理格式转换层。流程大致是安装 Ollama 并拉取模型比如ollama pull qwen2.5-coder:14b在 cc switch 中新增 Ollama providerBase URL 填写http://localhost:11434模型名填写你拉取的模型比如qwen2.5-coder:14b保存并切换然后在终端启动claude。需要提醒你的是本地模型的代码能力、上下文长度、指令遵循水平和云端 GPT-5、Claude Sonnet 这类大模型差距还是明显的。它更适合做代码补全、简单问答、短期离线测试别指望它独立完成大型重构。把期望放低一点它的价值才能体现出来。4. 核心使用技巧从“能对话”到“用得省”安装配置只是开始真正拉开差距的是使用方式。同样一个 Claude Code有人用它半天做不出一个功能有人半小时就能重构完一个模块差别就在对工具机制的理解。4.1 对话的基本姿势和提示词技巧Claude Code 不是搜索引擎你问得越模糊它发挥越不稳定。我总结的经验是至少要包含四要素项目背景这是什么项目、什么语言、什么框架目标你希望它做到什么效果约束不能动哪些文件、必须遵守什么规范验收标准怎样算完成比如“测试全部通过”“不能破坏现有接口”。举个例子差的提问是“帮我优化这个函数。”好的提问是“这个项目是用 Python FastAPI 写的utils/http_client.py里的fetch_data函数超时严重帮我加上重试机制只允许修改这个文件要求兼容 Python 3.10并补充对应单元测试。”另外强烈建议在项目根目录维护一份CLAUDE.md。每次新会话启动时Claude Code 都会自动读取这个文件作为背景信息。把项目结构、构建命令、代码风格、上线流程都写进去它能少问你好多废话。4.2 如何保存对话历史Claude Code 的会话历史默认是自动保存的文件存放在用户目录下的~/.claude/projects目录里每个项目对应一个 JSONL 文件。你可以直接用文本编辑器打开看也可以再次恢复。要恢复历史会话启动时加参数claude --resume或者直接在交互界面里使用/resume命令它会列出最近的会话你选择要恢复的那一个即可。如果你想手动导出某段对话可以输入/export它会以 Markdown 文件的形式导出当前会话内容。这个功能在做周报、记录调试过程时很好用。不过有一点要特别注意会话文件里包含了你的真实代码片段和执行命令可能还有敏感信息分享或者提交到 Git 仓库前一定要检查。4.3 怎么用少 token 做大事token 就是钱尤其是走 API Key 计费时节省 token 等于省钱。几个亲测有效的方法及时/compact对话太长后上下文窗口会塞满不仅慢而且贵。使用/compact把前面的内容压缩成摘要保留关键信息清出空间。用 CLAUDE.md 代替重复说明与其每次对话都解释项目背景不如把这些写进项目文档让 AI 每次自动读取。控制读取文件的范围不要让 AI 自己随便去读几十个文件。你应该明确告诉它“只看src/services下的文件”避免它浪费 token 遍历整个项目。拆任务一个大任务拆成几个小任务分步执行每次聚焦一个点。这看起来慢实际反而稳还省上下文。限制自动执行轮数启动时加claude --max-turns 10避免它陷入一长串无意义的操作循环。我自己实测的对比很夸张同样一个功能开发新手可能花掉 50 万 token熟练之后用 CLAUDE.md 精准范围控制可能只需要 10 万 token 左右。4.4 进阶玩法MCP、Skills、数据库和 PPTMCPModel Context Protocol是 Claude Code 连接外部工具的桥梁。你可以通过 MCP 让 Claude 直接读写数据库、操作浏览器、调用设计软件接口相当于给它装上“手和眼睛”。以读取数据库为例。你可以先安装官方数据库 MCP server比如claude mcp add postgres --env DATABASE_URL... -- npx modelcontextprotocol/server-postgres添加成功后再在对话里使用自然语言问“帮我查一下orders表最近一周每天的订单量”它就会自动连接数据库执行 SQL返回结果。这功能在数据分析、排查线上问题时非常香。Skills 则是另一套玩法。简单理解就是给 Claude 预设一份“技能包”让它按照固定流程去完成某一类任务。比如社区里有人做了 PPT skills通过 Python 脚本生成幻灯片你只要给出大纲和内容它就能直接在本地生成一个.pptx文件。GitHub 上类似模板很多比如claude code ppt skills、claude code skills你可以自己找找看原理都是把常用流程固化成文件让 AI 按照模板做事。注意MCP 和 Skills 确实能提升上限但也会带来安全风险。不要随意添加来源不明的 MCP server更不要让它读取本机敏感目录。我的原则是只添加自己看过源码的工具。5. Codex 和 Claude Code 到底怎么选热词里经常能刷到“codex和claude code有什么区别”“选codex还是claude code”。作为一个两个都用过的人我来说点实际感受帮你少走弯路。5.1 Codex 是什么Codex 是 OpenAI 推出的终端编程智能体定位和 Claude Code 非常像。它也是一个命令行工具你可以在项目目录下启动它用自然语言提出任务由模型分析代码、执行命令、修改文件。Codex 底层使用 OpenAI 的模型比如 GPT-5 / GPT-5-Codex和 ChatGPT 生态天然打通。如果你已经在使用 ChatGPT Plus 或 ChatGPT Pro那么 Codex 的订阅计费和网页版是绑定在一起的这是它最方便的地方。5.2 两者的核心差异对比我把主要差异整理成一张表方便你对照对比维度Claude CodeCodex底层模型Claude 系列Sonnet / OpusGPT 系列GPT-5-Codex 等付费方式Claude 订阅或 Anthropic APIChatGPT 订阅或 OpenAI API扩展生态MCP、Skills、大量社区配置相对封闭插件生态较少模型切换可通过环境变量/cc switch接入第三方默认仅 OpenAI 系灵活性弱一些代码风格对长上下文、多文件重构表现稳对复杂问题推理能力强但依赖模型选择上手门槛终端命令扩展工具较多终端命令本身也很轻量如果你已经在订阅 Claude那结论几乎是明摆着的直接用 Claude Code不用额外付费。如果你主力是 ChatGPT且不想再单独买一套订阅那么 Codex 更顺理成章。5.3 我的选择建议我两个都装但使用场景做了分工写 TypeScript 项目、做前端重构、处理长上下文时我更依赖 Claude Code。它的 MCP 生态确实强接数据库、接第三方工具很方便。做算法题、需要复杂逻辑推理、或者已经开了一个 ChatGPT 会话时我会用 Codex 或直接网页版。如果你问我“新人只选一个选哪个”我的建议是先看你已经付费了哪个生态付费是最真实的投票。如果两边都没订阅且你想更自由地接第三方模型比如 DeepSeek、GLM、本地 Ollama那 Claude Code 的开放性更高如果你只想开箱用、不想折腾配置Codex 和官方订阅绑定是更省心的选择。6. 高频报错与排查实录最后这部分是很多人问得最多的地方。Claude Code 整体很稳但新手期总会遇到各种奇怪问题。我把常见的集中写一下建议收藏备用。6.1 登录返回 403 怎么办登录 403 是热词中出现频率非常高的问题。我第一次遇到也很懵授权流程明明没问题却始终跳不过去。根据我的排查经验按顺序做这几件事先确认 Claude 账号本身有效浏览器打开网页版看看能不能正常登录在终端执行claude logout然后重新启动claude走一遍授权流程检查终端里是否有旧的登录缓存清理~/.claude/.credentials.json这个文件后重试如果网页版正常仅终端 403通常是本地环境的网络出口状态不稳定换个时间段再试或者重启路由器清洁网络环境。不要一上来就反复刷新授权码那样更容易被风控。稳定重试几次基本能解决。实在不行就暂时用 API Key 方式登录把ANTHROPIC_API_KEY设置好绕开 OAuth。6.2 模型识别报错“GLM-5.2 is not a model this version of Claude Code recognizes”这其实是接第三方模型时很典型的错误。意思是你的 Claude Code 版本没有把GLM-5.2这个模型名称加入到它认识的模型列表里所以它拒绝使用。解决办法升级 Claude Code 版本npm update -g anthropic-ai/claude-code确认模型名拼写是否正确常见的问题是glm-5.2写成GLM5.2或带了多余空格如果配置是通过 cc switch 写入的切回去重新保存一次确认没有残留旧配置也可以启动时显式指定模型claude --model glm-5.2绕过默认配置。出现这个错误并不代表模型能力不行而是这版 Claude Code 的“白名单”里没有它。通常升级到最新版就能解决大半问题。6.3 终端乱码问题Claude Code 在 Windows 终端里中文输出乱码是不少人遇到的第二个大坑。原因通常是终端的代码页不是 UTF-8或者输出的中文字符集和终端显示不一致。最简单的办法在 PowerShell 或 CMD 中执行chcp 65001把代码页切到 UTF-8 后再启动claude。如果你用的是 Windows Terminal默认设置就已经很好了我建议 Windows 用户直接用 Windows Terminal 而不是老版 CMD。也可以设置环境变量PYTHONIOENCODINGutf-8对部分涉及 Python 的脚本输出有帮助。还有一个土办法如果只是个别中文乱码而且你不想折腾环境直接告诉 Claude “这次请用英文输出日志”能临时绕过去。但解决根本问题还是切 UTF-8 代码页最靠谱。6.4 其他高频问题速查我把其他经常被问到的零碎问题整理成表格方便你快速查找问题现象原因解决办法claude命令找不到全局 bin 目录不在 PATH把 npm 全局目录加入系统 PATH安装时提示权限不足npm 目录受系统保护管理员运行或用 nvm 管理 Nodenpm 安装卡住不动默认源连接慢切换 npmmirror 镜像源对话越来越慢上下文太长使用/compact压缩上下文恢复会话找不到记录历史文件路径变更检查~/.claude/projects下的 JSONL 文件想彻底退出会话不清楚交互命令输入/exit或按CtrlC这些坑我基本都踩过一遍尤其是 PATH 和代码页这两个属于“新手最常问、老手看一眼就会”的问题。遇到报错别急着重装先按表格排查大概率能解决。我个人在实际操作中的体会是Claude Code 真正颠覆的并不是“能写代码”这件事而是把“改代码—跑命令—看报错—再修改”这个循环变短了。刚开始接触时别想着一口气让它完成整个项目先从修单元测试、重构一个小函数、生成 commit message 这种小任务入手。等你摸清楚它的脾气再一点点把更大、更模糊的任务交给它才会越来越顺手。最后再分享一个小技巧每次开始新项目之前花 30 秒在项目根目录写一个 CLAUDE.md把项目结构、构建命令、目录约定写清楚。就这一个动作能让它的工作质量立刻上一个台阶。