很多朋友第一次接触 Claude Code 时第一反应都是“这又是一个 IDE 插件吧”。我第一次用的时候也这么想装完才发现这玩意儿居然是在终端里跑的。没有图形界面没有悬浮按钮只有一个等待输入的提示符但它却能直接读你项目里的文件、改代码、跑测试、提交 commit甚至能把整个项目的结构梳理得明明白白。这篇教程就围绕 Claude Code 的安装和配置展开从零开始带你把完整流程走一遍包括环境准备、npm 全局安装、账号认证、VSCode 集成以及我在实际使用中踩过的那些坑。不管你是第一次听说 AI 编程助手还是已经用过 Copilot 这类工具的开发者只要电脑上能跑 Node.js都能跟着这篇文章把 Claude Code 装起来、跑起来。1. 安装前先把这几件事搞清楚1.1 Claude Code 到底是什么一个跑在终端里的编程代理如果把 Copilot 比作在编辑器里帮你补全下一行的“智能输入法”那 Claude Code 更像是一个真正坐在你旁边、能上手干活的实习生。你通过自然语言告诉它需求它在终端里自己调用工具、搜索文件、读取代码、修改内容、运行命令然后告诉你结果。它和传统 AI 编程助手的核心区别在于两点。第一它拥有执行能力不只是给建议而是可以直接改文件、跑脚本、操作 Git这是质的区别。第二它是终端应用不依赖特定编辑器这意味着不管你用 VSCode、IntelliJ、Neovim 还是纯命令行它都能工作。正因为这个特性Claude Code 更适合那些不排斥命令行、愿意读日志、能看懂 Git 状态的人。它更像一个需要你盯着干活的伙伴而不是一个全自动机器人。我见过不少完全没有终端基础的朋友安装完以后一脸懵因为启动之后面对的是一个命令行提示符不是漂亮的界面。这个心理预期要先建立起来。1.2 运行环境的基本要求不是所有机器都能直接上手Claude Code 是基于 Node.js 开发的所以环境要求不算苛刻但有几个硬指标要满足。操作系统macOS 10.15 及以上、Linux、Windows 10/11。Windows 下推荐使用 PowerShell 或者 WSL后面我会细说。Node.js官方要求 18 及以上版本我建议直接装最新的 LTS 版本目前是 20 或 22。Git需要能正常执行 git 命令并且已经配置好用户信息。网络必须能正常访问 Anthropic 的服务接口这个条件如果满足不了后面所有步骤都会卡在登录环节。如果你在公司内网先确认网络策略是否允许访问 Anthropic 相关域名在家用网络一般没有这个问题。很多人安装失败不是命令敲错了而是环境不满足。所以在正式安装前我建议你先打开终端依次执行node -v、npm -v、git --version这三个命令确认不会报“不是内部或外部命令”这类错误。如果这三个命令都正常输出版本号基础环境就没问题。1.3 账号与订阅Pro 会员和 API 计费是两条路线安装只是万里长征第一步真正卡住多数人的是认证环节。在用 Claude Code 之前你要先理清楚自己走哪条认证路线。认证方式适用人群计费模式首次认证操作Claude 账号登录Pro/Max 订阅个人开发者、日常编程按订阅制付费使用不额外按 token 计费运行 claude选择 Login跳转浏览器授权API Key团队、自动化脚本、企业级使用按 token 用量计费在 Anthropic Console 创建 API Key配置到本地我的建议是如果你只是自己写代码订阅 Pro 或 Max 方案就够了使用成本可控不需要盯着 token 用量。如果你是给团队搭建统一环境或者想写一些自动化脚本调用 Claude Code那建议走 API Key 路线便于统一管理和审计。账号还需要是在 Claude 服务支持的区域注册的账号这个问题很多人会忽略结果装好以后登录一直失败。所以我序言里反复强调先把网络环境和账号搞定再折腾安装命令。2. 基础环境搭建Node.js、Git 与终端准备2.1 Node.js 的版本选择和安装方式先说版本选择。Node.js 官方提供两条线Current 和 LTS。Claude Code 要求 Node.js 18所以我推荐 LTS也就是 20 或 22。不要用太老的 16.x我第一次用的时候就是 Node 16装完 Claude Code 启动直接报语法错误排查了半天才发现是版本太旧。Windows 用户最简单的方式是去 Node.js 官网下载 MSI 安装包一路下一步默认配置就行。如果你习惯用命令行也可以用 wingetwinget install OpenJS.NodeJS.LTSmacOS 用户如果有 Homebrew一行命令搞定brew install node22装完以后把/opt/homebrew/opt/node22/bin加进 PATH或者直接用 brew link。Linux 用户我强烈建议用 nvm 安装而不是直接用系统包管理器。因为系统自带的 Node 版本往往偏低而且升级麻烦。nvm 的好处是可以在多个 Node 版本之间随意切换后面想升级 Claude Code 依赖的 Node 版本时不需要重新折腾环境。装好以后验证一下node -v npm -v两个命令都输出版本号这一步就算过了。2.2 Git 安装与全局配置Claude Code 的很多操作都依赖 Git比如查看改动、创建分支、提交代码。如果你还没装 GitWindows 下直接从 Git 官网下载安装包macOS 一般自带Linux 用sudo apt install git或sudo dnf install git。装完 Git 以后有个很关键的步骤容易漏掉配置全局用户信息。如果没配置Claude Code 帮你执行 git commit 时会直接报错因为 Git 不知道提交人是谁。git config --global user.name Your Name git config --global user.email youexample.com这里建议用一个你经常用的 GitHub 邮箱提交记录里关联起来方便溯源。不要在每一台新电脑上都用不同的邮箱否则 Contribution 记录会变成一盘散沙。2.3 终端环境为什么 Windows 用户建议用 PowerShell 或 WSLClaude Code 是纯终端交互工具终端的体验直接决定你用它时的心情。Windows 下很多人习惯用 CMD我不会说你一定不能用但确实不推荐。CMD 对 ANSI 颜色转义支持得很差Claude Code 输出高亮信息时会出现一堆乱码交互体验一言难尽。建议这样设置使用 Windows Terminal PowerShell字体选 Cascadia Code 或 MesloLGS NF渲染效果会好很多。如果你的项目最终要部署到 Linux 服务器那更推荐装 WSL。WSL 里跑 Claude Code 几乎和 Linux 原生环境一样文件路径、权限模型、Shell 脚本行为都不需要额外适配。WSL 安装很简单管理员身份打开 PowerShell 执行wsl --install重启后按提示设置用户名密码即可。我目前的主力工作机是 Windows长期使用下来的组合是“Windows Terminal WSL 2 Claude Code”无论稳定性还是交互感受都很满意。3. 正式安装 Claude Code一行命令与安装后的首次自检3.1 使用 npm 全局安装安装命令非常简单就一行npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接执行claude命令。包名是anthropic-ai/claude-code注意不要少打前缀。安装过程长短取决于网络状况正常情况下一两分钟就能完成。如果你网络访问 npm 官方源很慢可以临时换成国内镜像源但这里我不过多展开网络问题大家都有自己的解决办法。安装完成后执行claude --version如果能看到类似1.0.x的版本号说明安装成功。3.2 安装后的自检清单装完以后不要急着用先花两分钟把下面几个检查项过一遍能省掉后面一大半的排查时间。检查项命令预期结果Node.js 版本node -vv18.0.0 及以上npm 可用npm -v输出版本号Git 可用git --version输出版本号Git 身份信息git config --global user.name输出你的用户名Claude Codeclaude --version输出版本号这五项全部通过你的安装环节就算真正完成了。如果哪一项是空的或者提示找不到命令直接把对应的问题解决再往下走。3.3 版本升级和卸载日常维护命令Claude Code 迭代非常快基本每一两周就会更新一个版本。官方会在终端里提示你有新版本可用这时你可以用一行命令更新npm update -g anthropic-ai/claude-code如果你是一段时间没用了想看看当前版本和最新版本的差距可以先查版本再决定要不要更新claude --version npm view anthropic-ai/claude-code version卸载更简单npm uninstall -g anthropic-ai/claude-code有一个细节多说一句Claude Code 的认证信息和配置数据存在~/.claude目录下卸载 npm 包不会删除这个目录。如果你想彻底清理需要手动删掉它。反过来如果你是重装系统后想恢复之前的配置把~/.claude备份一下就行装好新环境后直接放回去认证都能免掉。4. 认证配置登录与密钥让工具认识你的账号4.1 两种认证方式怎么选安装完成后直接执行claude它会先走认证流程。这一步是新手最容易卡住的地方因为报错信息往往不太友好。首次启动时CLI 会给你两个选择登录 Claude 账号或者配置 API Key。这里我结合自己的使用经验给出明确的选择建议。认证方式优点缺点推荐场景Claude 账号登录操作简单订阅制成本可控绑定的组织可能限制权限个人日常开发、个人项目API Key灵活可精确控制用量按 token 计费用多了费用上升团队、自动化和服务端场景如果你的日常工作重度依赖 Claude Code订阅制肯定比按量付费划算。我个人的使用习惯是 Pro 订阅为主跑大批量任务时会单独开一个 API Key两条路线互不干扰。4.2 完整登录流程和权限确认假设你选择订阅登录路线流程是这样的。执行claude后选择登录终端会显示一个链接和一次性授权码。浏览器打开链接、输入授权码然后点击允许按钮授权完成后终端会自动继续。这个过程本质上和你在网页上授权的流程是一样的只是入口在终端而已。登录成功后你会看到 Claude Code 的交互界面默认是流式输出模式能看到 AI 逐字生成内容。走到这一步认证就算真正完成了。授权信息会保存在本地的~/.claude目录里所以换电脑、重装系统后需要重新走一遍授权流程。如果你需要在一台新机器上快速恢复把原来的.claude目录复制过去是最省事的办法前提是你信任那台机器。4.3 组织策略导致的订阅访问报错这节我要单独拿出来说因为我被这个问题折磨了整整一个下午而且网络上有大量同样遭遇的人。错误提示是your organization has disabled claude subscription access for claude code。第一次看到这个提示我的第一反应是安装出问题了于是重装了 Node.js卸载重装了 Claude Code检查了 DNS甚至换了网络折腾一溜够问题依然存在。后来冷静下来仔细分析报错文本才发现问题出在“organization”这个词上。真实原因你的 Claude 账号如果属于某个组织常见场景是企业工作区、团队计划而该组织的管理员在后台关闭了 Claude Code 的订阅访问权限那么即使你个人订阅了 Pro也无法通过订阅方式使用 Claude Code。这是服务端权限策略不是本地安装问题。排查链路是访问 Claude 官网账号设置查看当前登录的账号是否绑定了企业组织。如果绑定的是公司工作区大概率就是这个问题。切换到个人账号试试用自己的邮箱注册的独立账号通常没有这个限制。如果你确实需要工作区账号让组织管理员去后台的 Member permissions 里开启 Claude Code 访问权限。如果管理员不配合或者你没有权限申请绕开订阅认证改用 API Key 方式。API Key 认证不走组织订阅授权流程能直接跳过这个限制。这个案例的教训是遇到解析不了的报错不要上来就重装先读一遍报错原文把关键词拆开分析往往能省几个小时。5. 与 VSCode 集成把 AI 助手放进最熟悉的编辑器里5.1 在 VSCode 中调用 Claude Code 的两种方式说句实在话Claude Code 并不需要强制配合某个 IDE 使用它在纯终端里就能完成所有事情。但对绝大多数开发者来说还是习惯在编辑器里看代码。这里分享两个我每天都在用的集成方式都不需要装额外插件。第一种直接在 VSCode 的集成终端里跑claude。按Ctrl 打开终端输入claude回车编辑器左边看代码终端下面和 AI 对话这个布局效率非常高。Claude 改文件时你能在编辑器里实时看到文件内容变化直观且安心。第二种调整布局把终端的显示位置放到右侧。适合那些需要同时盯着 AI 输出和代码改动的场景。具体操作是右键终端面板选择“移动面板位置”到右侧。有人问是不是有官方 VSCode 扩展。目前 Anthropic 官方没有推出 VSCode 扩展社区有一些第三方插件但我试过几个稳定性参差不齐有的授权方式还和官方 CLI 不一致。我的建议是直接用集成终端省心而且永远不会遇到扩展和 CLI 版本不匹配的问题。5.2 项目级记忆文件 CLAUDE.md 的配置Claude Code 有一个非常实用的机制叫 CLAUDE.md可以把它理解为“项目的操作手册”。每次会话启动时Claude 会自动读取这个文件然后按照里面的约定来行事。进入项目目录后启动claude输入/init它会自动扫描项目结构生成一个基础版 CLAUDE.md。但这只是起点想让 Claude Code 真正符合你的项目习惯必须手工精细化维护。以一个典型的前后端项目为例我的 CLAUDE.md 大概长这样# 项目说明 ## 技术栈 - 前端React TypeScript Vite - 后端Node.js Express - 数据库PostgreSQL ## 常用命令 - 开发npm run dev - 测试npm test - 构建npm run build ## 注意事项 - 不要修改 src/api 下的自动生成代码 - 提交信息统一使用 conventional commits - 改动数据库结构时必须先更新 migration 文件维护好这个文件之后你再让 Claude Code 改代码它的行为会明显收敛不再是一副“第一次见到这个项目”的样子。比如你之前告诉它后端接口路径、前端组件的组织方式它都会记住并沿用这些约定。一个常见误区是项目代码都写完了才想起加 CLAUDE.md然后又抱怨 Claude Code 不懂项目。正确的做法是项目一开始就配置好后续随着项目演进持续更新。5.3 实际工作流示例让它帮你改 bug、写测试理论说多了容易空我拿一个真实的工作流举例。假设测试反馈“用户登录接口报 500”你就可以启动claude然后输入帮我看看用户登录接口在哪个文件最近一次测试失败是什么原因。Claude Code 会自己搜索代码目录、定位路由文件、查看相关日志然后给你一个总结。接下来你可以继续要求直接修复这个 500 错误修复后跑一遍相关测试。它会开始修改文件、执行测试命令、根据测试输出继续调整直到测试通过。整个过程你只需要在关键节点上确认它要做的事情其余完全可以托管。我自己的经验是这类“定位问题—修改代码—验证结果”的循环是 Claude Code 最擅长的场景。但我要给一句忠告在它直接改代码之前先让它解释清楚问题和方案再放行执行。盲目批准 AI 的修改在小项目上问题不大一旦项目复杂起来很容易埋下隐患。6. 配置调优与踩坑记录6.1 常用配置项与模型选择Claude Code 的配置集中在~/.claude/settings.json项目级别也可以放一个.claude/settings.json覆盖全局配置。我挑了三个最值得关注的配置项说说。模型选择。Claude Code 支持切换不同模型常见的比如 Opus 和 Sonnet。我的使用体感是日常小任务、快速问答、改改局部逻辑Sonnet 又快又够用跨多文件重构、架构设计、复杂调试Opus 的理解深度明显高一个档次。你可以用/model命令在会话中实时切换不需要重启。Shell 权限控制。Claude Code 默认在执行 Shell 命令前排着确认这是安全底线。你可以通过权限规则把某些高频安全操作比如npm test、git status设置为免确认把涉及写文件的操作为保留确认。这样效率和安全能达到比较好的平衡。上下文控制。长会话容易导致上下文膨胀费用和响应延迟都会上升。合理使用/compact压缩对话历史或直接/clear开启新会话但要手动把重要上下文写进 CLAUDE.md避免丢失记忆。6.2 新手最常踩的 5 个坑把这段时间遇到的、看到的典型问题汇总成一个清单按出现频率排序。Node.js 版本过低。官方要求 18很多人机器上是旧的 14 或 16装完启动直接报错。解法就是升级到当前 LTS。在 CMD 里跑 Claude Code。显示严重错乱字体重叠严重影响判断。建议换 Windows Terminal PowerShell 或 WSL。Git 身份信息未配置。Claude Code 帮你提交时报错说缺少 user.name 和 user.email。执行那两条 git config 全局命令即可。账号绑定企业组织导致订阅访问被禁用。这个我前面已经详解过关键词是 organization disabled。项目太大时不给任何指引用 Claude 直接找文件它会在大量目录里反复横跳效率很低。建议在 prompt 里给出关键目录或文件路径让它从有限范围开始。6.3 和 Codex CLI 的对比以及我的选择建议现在提到终端里的 AI 编程助手绕不开两个工具Claude Code 和 OpenAI 的 Codex CLI。网上争论很多我两个都用了不短时间说说个人感受。对比维度Claude CodeCodex CLI底层模型Claude 系列GPT 系列安装方式npm 全局安装官网或 npm 安装认证方式Claude 账号 / API KeyOpenAI 账号 / API Key文件编辑能力强擅长跨文件重构和长上下文理解可用同样支持文件操作交互风格对话流程更完整会主动跟进执行结果偏向直接完成任务生态配合与 CLAUDE.md 深度绑定可沉淀项目知识相对轻量我的综合使用感受是复杂项目的重构、跨文件改动、长期维护的代码库Claude Code 的上下文感知能力更胜一筹尤其配合 CLAUDE.md 之后它越来越像熟悉这个项目的协作者。Codex CLI 在快速任务和简单修改上更利落。如果你让我给一个选型建议主力用 Claude 系列模型的开发者直接选 Claude Code已经在 OpenAI 生态里投入较多的Codex 也能干得很好。不建议双开并行更不建议两个工具同时操作同一个工作目录因为它们的文件修改和 Git 提交逻辑互不认识很容易搞乱提交历史。最后再分享一个我自己的小习惯。Claude Code 不是装好就完事的工具它的能力会和你的使用方法一起成长。我基本上每周都会把 CLAUDE.md 更新一遍把新项目的目录结构调整、代码规范补充进去。用的时间越长它越像团队里一个真正懂这个项目的人而不是一个每次对话都要重新介绍的临时工。如果你也想让它成为一个可靠的编程伙伴建议从一个小项目开始先建立项目记忆再逐步扩大使用边界。
