Claude Code 最近在开发者圈子里讨论度很高很多人把它当成一个普通软件来找安装包其实它和你平时装的那些图形化工具完全不同。我第一次上手时也绕了点弯路搞清楚它到底是个什么东西之后安装反而变得非常简单。这篇文章我不打算做成说明书式的“下一步点哪里”而是用实际操作的思路把 Claude Code 的安装、验证、VS Code 接入、Ubuntu/macOS 细节、账号登录以及接入 DeepSeek、Qwen、GLM 这类第三方模型的完整过程都过一遍。不管你是刚听说想试试的新手还是已经在终端里折腾过的老手这里面应该都有能直接用的东西。1. 安装之前先弄懂 Claude Code 的定位很多人一上来就搜“Claude Code 下载”结果找半天找不到一个.exe或.dmg文件。这是因为 Claude Code 根本就不是传统意义上的独立桌面应用。1.1 它是一个 CLI 编程助手不是独立 AppClaude Code 是 Anthropic 推出的命令行编程助手核心使用场景在终端里。它不是一个带窗口的聊天软件而是让你在项目目录下敲claude命令然后直接在终端里和 AI 对话、让它读代码、改文件、执行命令、跑测试的一套工具。这意味着安装它的方式也和传统软件不同不是去官网下载安装包而是通过 Node.js 的 npm 包管理器来安装。把 Claude Code 理解成“一个用 Node.js 写成的命令行工具”会更容易上手。这套设计的好处是它天然适配开发者已有的工作流。你不需要在编辑器和一个网页之间来回切换直接在项目根目录启动它它就能自动读取项目结构、Git 状态、代码内容。对于习惯终端的开发者来说这个体验比开网页版顺手得多。1.2 安装前必须确认的两样东西Node.js 和终端安装 Claude Code 的唯一前置条件是 Node.js版本要求通常是 18 以上。倒不是说必须装最新版但太老的 Node.js 会因为 API 不兼容导致 npm 安装失败或者运行时直接报错。确认 Node.js 版本的方式很简单node -v npm -v如果提示command not found说明你的机器上还没装 Node.js。装 Node.js 的话我建议优先考虑官方 LTS 版本毕竟 Claude Code 这类工具对运行时稳定性有一定要求。macOS 用户也可以直接用 Homebrewbrew install nodeUbuntu 用户常见的做法是通过 apt 装但 apt 仓库里的 Node.js 版本往往比较旧我更推荐用 NodeSource 维护的仓库或者安装 nvm 管理多版本。用 nvm 的好处是之后想切换 Node 版本非常灵活不会污染系统环境。1.3 不同平台的选择macOS、Ubuntu、Windows 的差异Claude Code 官方对 macOS 和 Linux 支持得最好Windows 用户通常需要借助 WSL 来运行这是因为它依赖 Unix 风格的终端环境和 Shell 命令。如果是在 Windows 上我建议优先把 WSL 环境搭好然后按照 Ubuntu 的方式在 WSL 里安装。直接在原生 Windows 上用 CMD 或 PowerShell 跑 Claude Code 经常会遇到各种奇怪问题排查起来非常浪费时间。macOS 用户相对省心只要装好 Node.js剩下的步骤和 Linux 几乎一样。Ubuntu 用户需要注意的点会多一些比如 Perl 的 locale 设置、PATH 路径、用户目录权限等这些我在第 4 部分会单独讲。2. 最快的安装路径一条 npm 命令Claude Code 官方推荐的安装方式就是通过 npm 全局安装。整个过程不需要下载压缩包、不需要配置环境变量最多两分钟就能跑起来。2.1 全局安装 anthropic-ai/claude-code 的完整流程在终端里执行下面这条命令npm install -g anthropic-ai/claude-code-g表示全局安装装好后claude命令就能在任意目录下访问。安装过程中 npm 会从仓库拉取并写入可执行文件通常十几秒到一分钟不等具体取决于网络状况。装完以后不要急着关终端先验证一下claude --version如果能看到类似0.x.x的版本号输出说明核心安装已经成功。第一次运行claude这时候 Claude Code 会引导你完成登录流程通常是在终端里显示一个链接让你打开浏览器授权然后把授权码粘贴回终端。具体登录相关的内容我在第 5 部分详细说。2.2 验证安装是否成功claude --version 与 claude doctor运行claude --version只是确认命令能执行并不能保证所有功能都正常。我建议再跑一下claude doctor这个命令会检查 Node.js 版本、环境变量、配置目录、登录状态等关键项并给出诊断结果。如果里面有红色或警告信息说明某些环节有问题需要提前处理否则后面使用时会踩坑。还有一个小技巧Claude Code 在首次启动时会初始化~/.claude配置目录。这个目录会存放你的配置文件和会话记录。如果发现claude命令能启动但无法持久化配置可以检查这个目录是否被创建、权限是否正确。2.3 在线升级claude update 和 npm 更新Claude Code 的迭代速度很快官方经常会加入新功能或修复 Bug。命令行工具内部自带升级命令claude update这个命令会检查最新版本并自动完成更新。如果claude update因为权限问题失败也可以用 npm 手动处理npm install -g anthropic-ai/claude-codelatest需要注意如果你的 Node.js 版本比较老升级到最新版 Claude Code 后可能会要求你同时升级 Node.js。我在实际使用中就碰到过一次旧版 Node 还能跑升级后直接提示版本过低只能把 Node 从 16 升到 18 以上。2.4 安装太慢怎么办npm 镜像源调整有很多人在安装时卡在 npm 下载这一步尤其是网络状况不太稳定的情况下经常是进度条半天不动。这时候最好的办法不是反复重试而是换一个更快的 npm 镜像源。临时指定镜像源安装npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com如果想长期全局生效也可以把 registry 写入 npm 配置npm config set registry https://registry.npmmirror.com不过我个人不太建议你把全局 registry 永久改掉因为之后发布或安装某些只在官方源里存在的包时会困惑。临时加--registry参数是最干净的做法。3. VS Code 里接入 Claude Code很多人的日常工作离不开 VS CodeClaude Code 也提供了对应的扩展插件。比起在终端里单独开一个窗口直接在 VS Code 里用 Claude Code 会更加顺手。3.1 官方扩展插件的基本逻辑在 VS Code 的扩展市场搜索 “Claude Code”找到 Anthropic 官方发布的扩展并安装。这个插件的逻辑不是把 Claude Code 重新实现一遍而是把你已经装好的 CLI 工具无缝集成到编辑器里。所以流程是先通过 npm 把 Claude Code 装好第 2 部分然后再装 VS Code 扩展。如果先装扩展但系统里没有 Claude Code CLI扩展会提示你先完成 CLI 安装。安装完扩展后VS Code 会识别claude命令。如果你机器上有多个 Node 版本或者在非标准路径安装了 Claude Code扩展可能找不到命令。这时候可以检查 VS Code 的终端环境和 PATH 设置确保claude在 PATH 中可见。3.2 从命令面板启动 Claude Code安装好扩展后按CtrlShiftPmacOS 是CmdShiftP打开命令面板输入 “Claude Code” 就能看到相关命令。通常会有打开 Claude Code 面板、安装/更新 CLI、查看文档等选项。选择启动命令后VS Code 会打开一个集成式的 Claude Code 界面你可以在里面直接描述需求让它读取左侧打开的项目文件并生成修改建议。这个体验比单纯在终端里跑命令更直观因为代码高亮、diff 预览都直接复用了 VS Code 的界面。实际上我更推荐另一种方式不依赖扩展面板直接在 VS Code 的集成终端里输入claude启动。集成终端的优势是它能自动继承当前工作区的环境变量和 Docker 配置减少很多上下文丢失问题。3.3 终端面板里使用 Claude Code 的推荐配置如果你打算长期在 VS Code 集成终端里用 Claude Code有几个配置值得提前设置。一个是在settings.json里调整终端默认 Shell确保使用 bash 或者 zsh 而不是 Windows CMD。另一个是打开 VS Code 的 “终端自动激活工作区环境” 相关配置这样每次启动终端都会加载项目所需的环境变量。还有一个实际经验如果项目很大Claude Code 在读取文件时可能会消耗比较多内存建议在 VS Code 设置里把终端渲染器的流畅度调高或者直接专注终端面板关掉右侧的资源监视器。这样操作起来不会卡顿。4. Ubuntu 与 macOS 的安装细节同一个 npm 命令在不同系统上遇到的问题完全不一样。这里把 Ubuntu 和 macOS 上常见的坑集中说一下。4.1 Ubuntu 常见权限与 Shell 配置Ubuntu 上用 npm 全局安装时最容易遇到的就是权限问题。如果你是用 sudo 装的 Node.js那么 npm install -g 的时候大概率会遇到 EACCES 错误提示没有权限写入/usr/lib/node_modules。有两个解决思路。一个是用 nvm 安装 Node.js这样全局包会装到用户目录下完全绕开系统权限问题。另一个是修改 npm 的全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把这个路径加到 Shell 配置里。如果是 bash编辑~/.bashrcexport PATH~/.npm-global/bin:$PATH改完记得source ~/.bashrc。这样之后执行claude就不需要 sudo 了。另外 Ubuntu 上还经常出现一个关于 locale 的警告因为 Claude Code 依赖 Perl 相关的组件如果系统 locale 没配置好运行时会提示perl: warning: Setting locale failed。这个不影响核心功能但很烦人。处理办法是确保系统装了完整的语言包或者正常配置LANG环境变量。4.2 macOS 安装时的系统弹窗与路径问题macOS 上如果是通过 Homebrew 安装 Node.jsnpm 全局包的路径通常是/opt/homebrew/bin一般不需要额外配置 PATH。但有一个细节macOS 的 Gatekeeper 会在首次打开某个命令行工具时弹出安全提示如果终端提示无法验证开发者需要到“系统设置 - 隐私与安全性”中手动允许。如果使用的是 zshmacOS 默认全局命令找不到时可以检查一下~/.zshrc确保 npm 的 bin 目录在 PATH 中。Homebrew 装的 Node 一般没问题但如果你用官方 pkg 安装包装的 Node有时会把路径指向/usr/local/bin需要确认一下。还有一个容易被忽略的点macOS 上的终端如果有 iTerm 和系统 Terminal 的差异环境变量可能不一致。你在一台终端里登录过 Claude Code换一个终端启动时却发现没有登录态大概率是环境变量或配置目录没有同步。遇到这种问题直接用同一个终端工具或者检查~/.claude目录是否存在。4.3 多用户环境的全局安装思路如果一台 Ubuntu 或 macOS 机器上有多个用户都要用 Claude Code每个人各自全局安装一份是最省事的方案互不干扰。官方虽然支持系统级安装但涉及权限和管理复杂度我实际测试过后不太推荐。比较合理的方案是给每个开发用户单独配置 nvm Node.js然后各自在用户目录下安装 Claude Code。同一个系统的多用户登录也不会出现配置互踩的问题。当然如果有 CI/CD 环境需要自动化安装那么可以在构建脚本里用 npm ci 或者 docker 镜像中预装这部分已经脱离日常安装范畴了遇到具体需求时再单独方案化。5. 登录账号注册和不注册到底差在哪安装完 Claude Code 之后有一个绕不开的问题要不要登录这背后的区别其实比很多人想象的更大。5.1 登录后能做的事登录 Anthropic 账号后Claude Code 会使用你的 Claude 订阅或 API 额度来驱动模型。也就是说你直接和 Claude Code 对话时背后跑的是 Claude 系列模型。登录方式也不复杂。首次运行claude时会输出一个授权链接浏览器打开后完成登录并授权系统会把密钥写回本机。之后再次运行就不需要重复登录了。登录的好处是开箱即用不需要自己配置任何模型端点或密钥。对于想快速体验的人来说这是最方便的路径。如果你已经订阅了 Claude 的相关服务或者有 API Key那么登录后直接干活就行。5.2 不登录模式适合第三方模型或纯 Harness 场景如果你没有 Anthropic 账号或者因为成本原因不想用官方模型Claude Code 依然可以启动只是默认情况下无法直接调用 Claude 模型。但这不代表它不能用。Claude Code 的真正架构是一个“Harness”外壳框架加上模型后端。模型后端是可以替换的。通过设置环境变量把请求指向任何兼容 Anthropic 接口格式的服务就能让 Claude Code 用别的模型跑起来。比较常见的做法是设置两个环境变量export ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_AUTH_TOKENyour_token_here设置好之后运行claude它就会走你指定的端点而不是官方 API。DeepSeek、Qwen、GLM 这类模型服务如果提供了 Anthropic 兼容的接口就可以这样接入。这个模式的好处是灵活、成本可控坏处是需要自己处理兼容性问题部分功能比如某些 Claude 特有的工具调用格式在第三方模型上可能表现不一致。5.3 账号切换与密钥管理的实践实际使用中我建议把不同场景的配置拆开管理。不要把所有密钥都写死在全局环境变量里否则切换模型或者排查问题时会非常痛苦。可以在项目目录下创建.claude/settings.json或者本地环境变量文件不同项目用不同配置。还可以用类似 direnv 的工具在进入特定目录时自动加载对应的环境变量。Claude Code 自己也会在~/.claude.json或~/.claude目录中保存登录凭证和配置。如果不小心把密钥泄露到公开仓库里第一件事是去对应平台吊销相关密钥然后重新登录生成新凭证。这个习惯比任何配置文件技巧都重要。6. 用 cc-switch 接入 DeepSeek、Qwen、GLM 等模型第三方模型接入是这个工具最吸引人的地方之一。光靠设置环境变量能解决但每次手动改来改去很麻烦所以社区里有人做了 cc-switch 这类切换工具。6.1 为什么能用第三方模型这里的关键在于 Anthropic 的 API 协议已经成为一个事实上的接口标准。很多模型服务商推出了 Anthropic 兼容接口比如 DeepSeek 官方就提供兼容模式用户只需要把请求地址从 Anthropic 官方换成服务商提供的地址就能在 Claude Code 中使用对应模型。这种兼容本质上是一个“协议适配层”Claude Code 不知道也不关心背后跑的是哪个模型它只按照 Anthropic 接口格式发请求、收响应。只要服务商的网关能正确处理这些请求Claude Code 就能正常工作。6.2 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 的配置方法接第三方模型核心就是上面提到的那两个环境变量。ANTHROPIC_BASE_URL是接口地址通常填服务商提供的基础 URL注意不要填错路径前缀有些服务需要你填完整路径有些只需要填域名级别具体看服务商文档。ANTHROPIC_AUTH_TOKEN是鉴权凭证一般是 API Key。我建议先用命令行验证配置是否生效env ANTHROPIC_BASE_URLhttps://your-endpoint ANTHROPIC_AUTH_TOKENyour_token claude如果启动日志里显示请求发往的地址是你指定的服务商地址说明配置生效了。如果还是请求 Anthropic 官方地址检查环境变量是否真的传进了当前终端进程。6.3 cc-switch 的界面化切换流程cc-switch 是一个社区工具它做的事情很简单维护多套 Anthropic 兼容 API 配置一键切换。你不用每次手动改环境变量省去很多重复劳动。cc-switch 的原理是修改 Claude Code 的配置或者生成一套启动脚本在启动前把当前选中的端点地址和 Token 注入进去。不同版本的 cc-switch 可能有不同的 UI有的是命令行菜单有的是网页面板但核心流程差不多在 cc-switch 中添加一个配置填好名称、Base URL、Token。需要切换时选择对应配置。重新启动 Claude Code让新的环境变量生效。注意切换配置前最好把当前 Claude Code 会话关闭否则已经加载的环境变量不会自动更新。我在切换模型时遇到过几次“好像切换了但实际还是老模型”的情况基本都是因为没有完全重启进程。6.4 NVIDIA NIM 等兼容端点的补充说明除了 DeepSeek、Qwen、GLM还有些本地或私有化方案也值得关注。比如 NVIDIA NIM 提供了一些模型的 Anthropic 兼容接口可以在自己的机器或内网环境启动一个端点然后把ANTHROPIC_BASE_URL指过去。这套玩法的价值在于数据不需要出内网模型可以私有部署适合对数据敏感或需要在离线环境开发的团队。安装流程和服务商接口类似只是端点是本地的。如果你的使用场景是离线或内网环境需要确认 npm 安装这一步已经提前完成因为后续运行时的依赖都在本地 Node 环境里不会再主动联网拉取。7. 常见问题与排查实录这里整理几个我实际遇到过的坑以及对应的排查思路。每个都按“现象 - 原因 - 解决”的顺序记录方便直接对照。7.1 命令找不到 claudePATH 问题现象执行npm install -g anthropic-ai/claude-code没报错但运行claude提示 command not found。原因npm 全局 bin 目录没有在 PATH 中。Ubuntu 上非 root 用户安装时非常常见macOS 上如果用了奇怪的 Node 安装方式也可能遇到。解决npm prefix -g这个命令会输出 npm 全局前缀路径。如果输出类似/usr/local那么 claude 应该在/usr/local/bin/claude。如果是其他路径手动把前缀/bin加入 PATH。加完以后重新打开终端再运行claude --version。7.2 权限不足 / EACCES 安装错误现象npm install -g 报错提示EACCES: permission denied, mkdir /usr/lib/node_modules/...。原因当前用户对系统全局目录没有写权限。解决要么用 sudo不推荐要么按第 4.1 节的方法设置 npm 前缀到用户目录。设置完别忘把新路径加进 PATH。7.3 npm 安装超时或网速极慢现象安装过程卡在下载阶段进度条很久不动最后报 timeout 错误。原因网络到 npm 官方源的连接不稳定。解决用--registry参数指向镜像源具体命令在第 2.4 节。执行完之后再验证一下版本号。如果还是失败可以清一下 npm 缓存再试npm cache clean --force还有一种情况是公司内网强制使用了自定义代理这时候需要给 npm 配置对应的代理设置但这个属于组织内部网络策略需要找你们自己的 IT 环境来确认不展开说了。7.4 登录后进不去项目或者识别不了本地仓库现象运行claude后它似乎没有读取当前目录的代码回复完全答非所问或者提示没有 Git 仓库。原因Claude Code 对项目上下文的依赖比较重它会自动识别 Git 仓库和项目结构。如果当前目录根本不是项目目录或者 Git 状态异常它获取上下文的能力就会被限制。解决在项目根目录通常是有.git目录的那层启动claude。如果你确实需要临时使用也可以先确认目录的 Git 状态是否正常修复异常后再启动。有些版本还支持忽略当前目录直接读取指定目录但这个能力往往会因为权限或配置原因不太稳定我一般还是老老实实切换目录。另外如果你的项目里包含大量二进制文件或巨大的 node_modulesClaude Code 在读取上下文时可能会有点慢这时可以考虑在.claude配置里设置忽略规则减少不必要的文件扫描。7.5 快速参考表问题可能原因快速处理command not found: claudenpm 全局 bin 不在 PATHnpm prefix -g找到路径加入 PATHEACCES 安装失败用户无系统目录写权限改 npm prefix 到用户目录npm 下载超时网络连接官方源不稳定临时加--registry镜像源版本更新失败Node.js 版本过旧升级 Node.js 到 18登录状态丢失多终端环境变量不一致检查~/.claude目录重新登录第三方模型不生效环境变量没正确传入进程用env前缀直接启动验证无法识别项目启动目录不是项目根目录进入正确目录或用 Git 确认仓库状态8. 进阶配置让 Claude Code 更贴合自己的工作流安装只是第一步真正让 Claude Code 变得好用的往往是一些不起眼的小配置。8.1 项目级与全局配置的分层管理Claude Code 支持在多个层级设置配置。~/.claude下的配置是全局的适合放一些跨项目通用的偏好。项目目录下的.claude/settings.json则是项目级配置适合放这个项目特有的指令、权限策略、忽略规则。我的习惯是全局配置只放模型偏好、主题、常用权限白名单项目配置放针对这个代码库的上下文提示比如“这个项目使用 Python 3.11 FastAPI测试命令是 pytest”。这样一来每次切换项目时 Claude Code 会自动加载对应的上下文回答准确率会明显提升。8.2 权限与安全的实操建议Claude Code 能够直接执行终端命令这既是强大也是风险所在。它会在执行命令前征求你的确认但如果你开启了自动确认模式一些有副作用的命令比如rm -rf、git push --force就会直接执行。我强烈建议在涉及删除、推送、生产环境部署等危险操作时不要把权限配置成自动放行。在配置文件中明确禁止这些命令或者保持手动确认模式。这个习惯能帮你避免很多不可逆的损失。8.3 常用 alias 与工作流组合如果你把 Claude Code 作为日常开发的一部分可以考虑在 Shell 里加一个简单别名省得每次输全命令alias ccclaude我个人的工作流是在 VS Code 集成终端里用cc启动让它先读一遍项目结构然后把需求描述清楚。需要切换模型时用 cc-switch 换配置并重启会话。这一套流程用下来比在多个工具之间来回切换舒服很多。最后再分享一个小技巧Claude Code 的会话上下文是连续的但如果你切换分支、大幅度重构代码旧的上下文可能已经过时。这时候不要硬问直接开一个新会话把当前的项目状态重新交给它读一遍。看起来浪费了一点时间实际上比在旧上下文里纠错高效得多。