1. Claude Code 是什么先建立全景认识1.1 核心定位终端里的结对编程助手Claude Code 是 Anthropic 推出的一款跑在终端里的编程助手。它不像普通聊天机器人那样只给你一段回答而是能直接读取你的项目目录、查看文件、运行命令、修改代码然后把结果反馈给你。我第一次用的时候最直观的感受是它像一个愿意自己动手的结对程序员坐在你旁边你不光能跟它讨论思路还能直接让它改 bug、补测试、跑构建。它解决的核心问题很明确把“聊代码”和“改代码”之间那层传递成本降到最低。传统 AI 编程流程是“复制代码到对话框 - 等结果 - 再粘贴回来”Claude Code 的模式是“直接在项目里开工”所有操作都发生在你本地的上下文里。适合的人群也很广独立开发者、前端/后端工程师、运维、数据工程甚至刚入门编程但能操作终端的新手。因为标题里带了“中英文教程”我多说一句这篇记录里的核心术语我都会保留英文原词比如 CLI、Agent、MCP中文含义会同步解释。这样你以后去查官方文档、搜 GitHub issue不会被中文翻译带偏。1.2 关键术语中英文对照英文术语中文理解出现场景Claude Code终端编程助手本篇文章的主角CLICommand Line Interface命令行工具安装、启动、日常操作Agent / Harness自主执行的智能体框架让 Claude Code 自己调用工具、执行命令MCPModel Context Protocol模型上下文协议连接外部工具/数据源的开放标准VS Code ExtensionVS Code 扩展插件在编辑器里直接使用 Claude CodeBase URL接口基础地址切换第三方模型时的关键配置API Key接口密钥不登录账号、走 API 计费时使用1.3 适合谁用解决什么问题如果你是纯新手从没碰过终端Claude Code 的上手门槛主要在安装环节跨过去之后反而比 IDE 插件更简单——因为所有交互都收在一个命令行窗口里。如果你是有经验的开发者它最有价值的地方是处理重复劳动重构命名、补测试用例、批量修改文件、解释陌生项目结构。运维类需求它也能干比如让你执行命令、看日志、排查端口占用配合“直接执行终端命令”的能力效率上限很高。2. 安装前的准备与环境要求2.1 确认系统与运行时Claude Code 本质上是一个基于 Node.js 的命令行工具所以最推荐、最稳的安装路径是 npm 全局安装。在你执行安装命令之前先确认三件事系统Windows 10/11、macOS、Ubuntu 等主流 Linux 发行版都支持。Node.js 版本建议 18 以上最好直接上 20 LTS 或更新版本。版本太低会出现找不到模块、安装失败等奇怪问题。终端环境Windows 推荐使用 PowerShell 或 Windows TerminalLinux/macOS 用系统自带终端即可。检查 Node 版本的命令是node -v npm -v如果提示node: command not found说明 Node.js 还没装。macOS 可以用 Homebrew 装brew install nodeUbuntu/Debian 系列系统不建议直接apt install nodejs因为版本往往偏旧。我更推荐先装 nvmNode Version Manager再用 nvm 装指定版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20Windows 用户直接去 Node.js 官网下载 LTS 安装包即可安装时勾选“Add to PATH”。2.2 账号与订阅怎么选很多人一开始都会纠结注册账号和不注册账号的区别。我直接给你拆清楚使用方式是否要登录计费方式适合场景Claude 账号 Pro/Max 订阅需要 OAuth 登录订阅制日常写代码、个人项目Anthropic 控制台 API Key不需要 Claude 登录按 token 用量计费开发、自动化脚本、团队共享第三方模型 APIDeepSeek、Qwen、GLM 等不需要 Claude 登录服务商单独计费便宜、可控、模型切换频繁本地模型LM Studio不需要任何登录纯本地几乎零成本离线场景、隐私敏感项目、模型玩法探索实际体验上的差异也很明显用 Claude 账号登录时命令输入框里能看到订阅套餐状态模型能力默认拉满。不登录直接启动只会看到欢迎界面无法真正对话。如果你用 API Key 或第三方模型Claude Code 会通过环境变量识别身份启动时完全跳过登录流程直接进入工作状态。提示如果你在团队或公司环境下使用遇到your organization has disabled claude subscription access for claude code这类提示说明组织策略层面关闭了 Claude Code 的订阅访问通道这属于管理员在后台配置的开关不是本地能改的设置。3. 安装与升级实操Windows、macOS、Ubuntu3.1 推荐路径npm 全局安装无论你用哪个操作系统只要 Node.js 环境正常安装命令只有一条npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version如果能输出版本号说明安装成功。接下来直接在项目目录里启动cd your-project claude第一次运行会引导你完成登录流程。如果你没有 Claude 账号可以先注册一个免费账号或者准备好 API Key 后通过环境变量方式启动。macOS 用户如果不想通过 npm也可以用官方提供的原生安装脚本具体命令以官方文档为准。Ubuntu 系统同样支持原生安装但我的建议是优先 npm因为后续升级和维护更统一不容易出现权限问题。3.2 原生安装器与桌面版除了 npm 包Claude Code 官方也提供原生安装器适合不想碰 Node 生态的人。原生安装的好处是启动更快、不依赖 npm 全局目录权限。缺点是不同平台的安装包区别较大Windows 上还容易出现“位数不匹配”的报错所以没有特殊需求时我仍然建议 npm。关于桌面版注意区分两个概念一个是 Claude 的桌面客户端另一个是 Claude Code 桌面版。命名上容易混淆。你在官方文档里搜到的 “Claude Code Desktop” 通常是 CLI 的图形化配套入口本质还是同一个引擎。安装包尽量从官方渠道下载第三方站点发布的“桌面版安装包”版本陈旧反而容易触发兼容性问题。3.3 在线升级到最新版本Claude Code 的版本迭代很快新模型、新工具调用方式经常跟着版本走。查版本和升级# 查看当前版本 claude --version # 如果有自动更新提示在交互式会话里执行 claude update # 或者直接用 npm 强制升级 npm install -g anthropic-ai/claude-codelatest我习惯每次写代码前顺手跑一句claude --version看到有新版就直接升。有一个细节如果你是通过原生安装器装的用claude update更合适如果你是通过 npm 装的npm install -g会覆盖旧版本两条路不要混用否则可能出现“命令还在但版本没变”的错觉。4. VS Code 接入与桌面端配置4.1 安装官方扩展Claude Code 的命令行体验很好但不少场景我还是要回到 VS Code 里看代码、看 diff。这时候直接切终端有点打断节奏所以 Anthropic 官方提供了 VS Code 扩展。打开 VS Code 扩展市场搜索 “Claude Code”认准官方发布者点击安装。装完之后左侧会出现对应图标点击图标就能在编辑器侧边栏直接启动一个 Claude Code 会话。它的底层还是命令行工具所以你在终端里已有的登录状态、模型配置、权限设置都会同步生效。命令行和扩展二选一也完全没问题但我的使用体验是集中式重构的时候用终端更顺手边看代码边问问题的时候用扩展更直观。两者共用同一套项目上下文不会出现“这边聊完那边不知道”的问题。4.2 扩展配置细节VS Code 扩展最常见的配置问题是找不到claude命令。原因通常是全局 npm 目录没有加入 PATH。解决办法是在 VS Code 设置里手动指定{ claude-code.path: /usr/local/bin/claude, claude-code.autoStart: true, claude-code.cwd: ${workspaceFolder} }其中claude-code.path要填你本机claude命令的实际路径。macOS/Linux 下可以用which claude查到Windows 下通常在 npm 全局目录下。claude-code.autoStart控制是否在打开工作区时自动初始化 Claude Code 会话我建议关掉等需要时再手动启动不然每次打开项目都要等初始化。claude-code.cwd表示运行目录默认是当前工作区如果你需要固定跑某个子项目改成子项目路径更稳妥。如果你需要在扩展里使用第三方模型对应环境变量同样要配置到 VS Code 的 settings.json 里而不是只在终端里 export。因为扩展启动的 Claude Code 进程不一定继承你 shell 里临时设置的环境变量。5. 第三方模型接入换掉默认模型5.1 原理环境变量切换Claude Code 默认走 Anthropic 官方接口但它同样支持通过环境变量把接口地址、认证 token、模型名全部覆盖。这套机制是第三方模型接入的基础。核心环境变量有三个export ANTHROPIC_BASE_URLhttps://api.example.com export ANTHROPIC_AUTH_TOKENsk-xxx export ANTHROPIC_MODELyour-model-name设置之后直接运行claude它会跳过 Claude 账号登录用你指定的接口地址和 token 发起请求。只要目标服务端兼容 Anthropic 的 Messages API就能正常使用。很多模型服务商比如 DeepSeek、Qwen、GLM 的开放平台都开始提供 Anthropic 兼容端点。你只需要去对应控制台找到 “Anthropic API” 或 “Claude Code 接入地址”把地址填进上面三个变量就行。如果某个服务商只提供 OpenAI 兼容端点那就需要在中间加一层协议转换LiteLLM 这类代理工具可以完成这个工作。注意用第三方模型时实际效果好不好取决于模型本身是否擅长“工具调用”。Claude Code 的工作方式不是单纯聊天它需要模型能理解工具返回结果、决定下一步该执行什么命令。太弱的模型会出现“假装执行成功”或“反复做无用操作”的情况。5.2 用 CC Switch 管理多供应商如果你频繁在 DeepSeek、Qwen、GLM 之间切换手动 export 环境变量非常容易出错。社区里常见的解决方案是 CC Switch一个小工具专门用来管理 Claude Code 的多套供应商配置。CC Switch 的用法很简单把每个供应商的 Base URL、API Key、模型名保存成一套配置切换时点一下它会自动帮你把当前 shell 或配置文件里的环境变量改好。我个人对这类工具的建议是可以先理解它背后的原理因为它本质上还是在写环境变量只是把“手写”变成了“界面化”。如果你不想依赖第三方工具也可以在自己的 shell 配置里做几个 aliasalias claude-deepseekexport ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-deepseek-key export ANTHROPIC_MODELdeepseek-chat claude alias claude-glmexport ANTHROPIC_BASE_URLhttps://open.bigmodel.cn/api/anthropic export ANTHROPIC_AUTH_TOKENsk-glm-key export ANTHROPIC_MODELglm-4.5 claude这样每次切换就是敲一个短命令的事还避免了配置串台。5.3 调用 LM Studio 本地模型调用本地模型是很多人的刚需尤其是隐私敏感项目、纯离线环境或者想低成本玩模型切换的场景。LM Studio 是目前比较流行的本地模型运行工具支持加载 GGUF 格式模型并提供 OpenAI 兼容的本地接口。先说结论Claude Code 默认不直接兼容 OpenAI 的/v1/chat/completions接口所以如果你想用 LM Studio 跑本地模型需要在中间加一层协议转换把 Anthropic 格式翻译成 OpenAI 格式。常见方案是用 LiteLLM Proxy 或类似工具。步骤大致如下在 LM Studio 里加载一个代码模型比如qwen2.5-coder-7b-instruct。打开 LM Studio 的 Developer 面板启动本地服务器端口默认是 1234。写一个 LiteLLM 配置文件model_list: - model_name: claude-code-local litellm_params: model: openai/qwen2.5-coder-7b-instruct api_base: http://localhost:1234/v1 api_key: lm-studio启动 LiteLLM 代理litellm --config config.yaml --port 4000配置 Claude Code 使用本地模型export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-dummy export ANTHROPIC_MODELclaude-code-local claude如果你有 NVIDIA 显卡LM Studio 会自动走 CUDA 加速不需要额外配置只要驱动装好就行。本地模型的好处是私有、免费、可控坏处是模型能力普遍弱于顶级云端模型复杂项目里的实际完成度会打折扣。拿本地模型做“辅助小任务”很合适做完整的大型重构会比较吃力。6. 核心功能实战从对话到执行终端命令6.1 第一次启动与基本对话安装完成后在项目目录运行claude你会看到一个交互式输入框。第一次使用建议直接从简单任务开始比如请看一下这个项目的目录结构告诉我它的技术栈和入口文件在哪里。Claude Code 会调用终端工具列出文件读取关键配置文件然后给出结构化的回答。这个过程中你会注意到它不像普通聊天机器人那样一次性输出长篇内容而是会显示“正在读取文件”“正在执行命令”这类中间状态这是因为它真的在操作你的项目。对话中可以直接用自然语言提要求把 src/utils 下的工具函数按功能拆分成多个文件并更新所有引用。它会先分析当前代码制定改动计划然后逐文件修改。每次改动前它通常会询问你确认这是权限机制的一部分。具体表现受你启动时的权限模式影响。6.2 让 Claude Code 直接执行终端命令Claude Code 可以直接执行终端命令这也是它被称为 Agent 而不是聊天机器人的关键原因。默认情况下它执行命令前会征求你的确认。比如你说“跑一下测试”它会先展示要执行的命令npm test你确认后它才运行然后把输出结果拿回来继续分析。遇到测试失败它会尝试修复代码再重新执行测试形成“失败 - 修复 - 重跑”的闭环。如果你希望它自动执行不逐个确认可以启动时加参数claude --dangerously-skip-permissions这个参数的名字已经写得很直白了跳过权限检查。它适合在容器、CI 环境或你完全清楚项目影响范围的情况下使用。在本地开发时我不推荐长期用它因为一旦模型理解偏差它可能会执行你不想执行的破坏性命令。另一个实用技巧是直接以命令形式调用claude 清理 dist 目录里超过 7 天的临时文件它会根据你的自然语言指令转换成对应的终端命令并执行。这种方式适合脚本化、定时任务化。6.3 大型任务的执行模式处理大型任务时Claude Code 会拆解步骤而不是一口气乱来。举个例子你让它“给这个老项目补上单元测试”它可能会这么做先读取现有测试框架配置分析哪些模块有测试覆盖、哪些没有按模块优先级逐个生成测试文件运行测试并修复失败用例最后汇总改动范围和覆盖情况这个过程可能需要执行几十次命令、读写几十个文件。你不需要每一步都手动干预但建议保持终端可见注意看它每一步做了什么。一旦发现方向错误直接按Esc或CtrlC中断然后补充一句更明确的指令这比让它一路跑偏再返工效率高得多。7. 常见问题与排查技巧实录7.1 组织策略报错不少公司会统一管理 Claude 订阅。遇到这类报错时正确做法是联系管理员确认是否放行而不是自己绕策略去改配置。如果管理员暂时无法开放你可以走个人账号 API Key 的方式但要注意不能违反公司数据安全规定。7.2 Windows 64 位兼容性问题有用户反馈过“Claude Code 与 64 位 Windows 不兼容”的弹窗。根据我踩坑的经验这类问题通常有三个原因安装的是旧版原生安装包和当前系统版本不匹配系统缺少运行库比如 VC Redistributable终端环境下没有正确识别 Node.js 路径解决办法先卸载旧版本通过 npm 重新安装最新版确认 Node.js 是 64 位 LTS最后在 PowerShell 里跑一次claude --version验证。如果还不行去 VS Code 扩展设置里检查claude-code.path。7.3 地区可用性提示启动时如果看到Claude Code might not be available in your country说明当前账号或网络环境不在官方支持范围内。我的建议直接一点去官方文档核对支持地区列表或者联系官方支持确认。不要使用任何非官方手段绕开限制那既违规也容易让账号风控不值当。7.4 其他高频问题速查表问题现象常见原因处理方式command not found: claudenpm 全局目录不在 PATH用npm prefix -g找到路径并加入 PATH启动后卡在登录页网络或账号 token 过期重新登录检查浏览器弹窗是否被拦截第三方模型返回 401API Key 或 Base URL 错误核对控制台配置确认没有多空格本地模型响应很慢量化位数过高或显存不足换更小模型检查 GPU 加速扩展里启动失败环境变量没有同步给扩展把变量写进 VS Code settings.json升级后旧配置失效版本更新改了配置结构查看官方 changelog按新版格式重新配置8. 扩展玩法与实际体会8.1 把执行结果推送到飞书群如果你想让 Claude Code 跑完任务后通知团队可以把它和飞书群机器人接起来。原理很简单飞书群里添加一个自定义机器人复制 Webhook 地址然后让 Claude Code 在任务结束时调用 webhook 发送消息。示例如下curl -X POST -H Content-Type: application/json \ -d {msg_type:text,content:{text:Claude Code 已完成任务请查看结果。}} \ https://open.feishu.cn/open-apis/bot/v2/hook/你的机器人地址你可以直接把这个命令交给 Claude Code 执行也可以把它写进项目的脚本里。这样团队协作时AI 助手的执行结果就能自动同步到工作群省去人工转发。8.2 我的使用习惯与避坑建议用了一段时间后我最大的体会是Claude Code 强大的前提是项目目录干净、上下文可控。它会把整个项目目录作为上下文项目里塞满 node_modules、dist、临时文件时它的判断会被大量无关信息干扰。建议在项目根目录配置忽略文件限制它扫描的范围。另外别把它当搜索引擎用。它是“执行者”不是“万事通”。问它“这个 API 怎么调”可以但真正有价值的是让它直接帮你调通 API、处理报错、补完代码。最后一个小技巧每次开始大任务前先让它输出一份计划确认计划对不对再让它放手干。这一步能省下大量返工时间。我也习惯把常用的指令组合保存成笔记比如“代码 review 指令”“测试补全指令”“依赖升级指令”。用熟了之后你会发现 Claude Code 真正的价值不是替你写代码而是替你省掉大量“打开文件 - 理解上下文 - 改代码 - 跑测试”的重复循环。