★ FEATURED ARTICLE 1. 安装之前先理清四个问题1.1 Claude Code 到底是干什么用的我先讲个实际场景。前阵子调试一个跨平台小项目日志一屏一屏往外滚改完代码又得切回浏览器去问 AI来来回回不知道浪费了多少时间。后来我换成了 Claude Code直接在终端里启动让它读当前目录下的源码、解释报错、给修改建议甚至直接帮我把命令跑了整个工作流顺畅了不少。Claude Code 本质上是一个跑在命令行里的 AI 编程助手。它和网页版最大的区别不是交互形式而是“工作位置”网页版像一个顾问你需要把代码复制过去而 Claude Code 直接站在你的项目目录里能看到文件结构、能读源码天然贴近开发场景。修 bug、查日志、改配置、写测试脚本这些都能在同一个终端窗口里完成不用来回切上下文。适合用它的人是那些日常在终端里干活、习惯用 Git 命令或者 SSH 上服务器操作的人。如果你平时更依赖图形化 IDE 的插件或者只是想找个人聊聊天那它就不是最优选择。所以我在动手安装之前会先问自己一句我到底是要“在项目上下文里干活”还是“找一个对话窗口”。想清楚这一点后面选安装方式、配权限都会顺畅很多。对刚上手的人来说第一反应通常是到处找安装包下载地址。我的建议是先别急因为 Claude Code 的安装方式高度依赖你当前的系统环境Windows 和 macOS 走的路子有重合也有明显区别。后面我按系统分开写你直接跟着自己对应的那部分操作就行。1.2 Windows 和 macOS 安装思路的差异先说结论两个平台的安装逻辑大方向一致差异主要集中在 shell 环境、包管理器和路径配置上。Windows 默认的终端是 PowerShellmacOS 默认是 zsh。Claude Code 的安装路径通常有两种主流方式一种是通过 Node.js 生态里的 npm 做全局安装一种是直接下载官方打包好的二进制文件。两种方式跨平台都能用但 npm 方式更通用后面升级、卸载、管理依赖都方便所以我个人更推荐先把 Node.js 环境铺好再走 npm 安装。macOS 用户还有一个常见习惯就是优先用 Homebrew 管理命令行工具。brew 的优势是统一管理、卸载干净缺点是如果机器上本来没有 Homebrew装它本身就要费不少时间。Windows 上也有 WinGet 或 Chocolatey 这类包管理器但第三方仓库的更新往往滞后而且不同仓库间的打包方式参差不齐新手容易踩坑。我的原则是先选一条能跑通的路线别在“选工具”上内耗太多。等你把 Claude Code 跑起来之后再根据实际体验决定要不要换成 Homebrew、WinGet 或者其他方式。安装这个动作本身只需要几分钟真正花时间的是后续的使用习惯。1.3 真正的前置条件动手安装之前我建议你先做一轮环境自检下面四项是高频问题来源。第一是系统版本。Windows 10 或 11macOS 12 及以上目前来看问题不大如果你的系统特别老可能会碰到底层依赖不支持的情况这时候优先考虑升级系统而不是硬装。第二是网络连通性。Claude Code 启动后需要连接服务端如果你的网络环境有额外的访问限制或者本机开着系统级的网络转发工具就很容易出现“安装成功但启动超时”的情况。注意我这里的表述不是让你特别去调整什么网络策略而是提醒你遇到超时先把本地网络环节排查一遍。第三是账号和认证信息。工具本身需要有可用的 Claude 账号。如果你打算走 API 计费方式还得准备好密钥如果走订阅账号授权那首次启动时会引导你在浏览器里完成登录。第四是 Node.js 环境。npm 安装方式依赖 Node.js版本太旧会导致各种奇怪的权限和下载错误。建议提前装好 LTS 版本并且在终端里执行node -v和npm -v确认版本号能正常输出。这四项看着基础但至少解决了 80% 的安装问题。我见过太多人安装了半小时最后发现只是因为 Node 版本太旧或者终端没重启。1.4 先确认官方渠道再安装这条我想放在安装前单独说因为它是最重要的习惯。网上关于 Claude Code 的安装教程很多有的一键脚本确实方便但我不推荐直接用。命令行工具的命令名、包名和认证方式会随版本变化第三方脚本很可能还停留在旧版本甚至会顺手修改你的 shell 配置文件。我自己的习惯是每次安装前先打开官方文档或官方代码仓库确认三件事——当前推荐的安装命令、最新版本号、有没有针对 Windows 或 macOS 的特殊说明。这一步花不了五分钟但能帮你少踩很多坑。另外要提醒一点官方仓库的 README 里通常会给出版本更新记录建议顺手扫一眼最近几个版本的变化。有些版本会有配置项迁移、默认行为调整提前知道能避免升级后一脸懵。2. Windows 安装的完整过程2.1 先把 Node.js 环境铺好Windows 上装 Node.js 最省事的方式就是去官网下载安装包。有两个地方容易踩坑第一选择 LTS 版本不要选最新的实验版稳定性优先第二安装向导里务必勾选“Add to PATH”否则后面终端里找不到 node 命令又得手动去配置环境变量。如果你的电脑上已经装过旧版 Node.js我建议先卸载干净再装新的。旧版本残留和新版本混在一起很容易出现node -v显示一个版本、npm -v显示另一个版本的情况排查起来非常头疼。如果你需要在多个 Node 版本之间切换可以装一个叫 nvm-windows 的版本管理器这个方案比手动切换干净得多。安装完成后打开一个全新的 PowerShell 窗口分别执行node -v和npm -v。这里强调“全新”两个字是因为旧终端窗口不会自动加载新加入的 PATH 环境变量。很多人在这一步遇到“无法识别”的提示其实就是没开新窗口根本原因很简单。如果重新打开窗口依然提示找不到命令那就要手动去“系统属性 - 环境变量”里检查 PATH。把 Node.js 安装目录和 npm 全局模块目录都加进去保存后再次打开新窗口验证。2.2 使用 npm 全局安装 Claude Code环境没问题之后打开 PowerShell按官方文档里的命令执行全局安装。整体命令形如npm install -g 官方包名注意尖括号里的包名要以你查到的官方信息为准不要拿占位符直接复制。我在实际安装时就遇到过包名写错的情况npm 提示找不到包后来核对才发现是教程里写的是旧名字。安装过程如果遇到权限相关报错先别急着“以管理员身份运行”。管理员权限虽然能强行写文件但会把 npm 全局目录的权限关系搞乱后续升级会很麻烦。更好的做法是把 npm 的全局目录指到当前用户目录下具体操作可以查 npm 官方文档这里不展开。安装完成后终端里会出现claude命令。顺手跑一下claude --version能输出版本号就说明安装这一环已经完成了。这一步最容易出现的是网络超时尤其是 npm 默认源访问慢的时候。遇到下载缓慢可以先检查是不是源的问题临时换一个访问更快的源装完之后记得切回默认源避免后续依赖解析异常。2.3 首次启动与登录认证在项目目录里敲下claude第一次启动会进入初始化流程。通常会有两种登录方式一种是通过浏览器完成账号授权另一种是直接粘贴 API 密钥。浏览器授权适合订阅制用户体验上更接近日常使用API 密钥方式适合没有浏览器的远程服务器环境也适合脚本化调用。如果你是在本机操作两种都能选看你的账号类型而定。登录成功之后工具通常会把凭据缓存到用户目录下的配置文件夹里第二次启动就不需要重新登录了。这里有一个非常重要的习惯要养成不要把这个配置文件提交进 Git 仓库特别是项目目录内生成的配置文件里面可能包含敏感信息。建议在项目根目录维护一份.gitignore把配置相关文件加进去。2.4 处理 PowerShell 执行策略Windows 上遇到最典型的报错是执行claude时 PowerShell 提示“无法加载文件因为在此系统上禁止运行脚本”。这个问题和 Claude Code 本身没关系是 Windows 默认的执行策略限制了脚本运行。先执行下面这条命令查看当前策略Get-ExecutionPolicy如果结果是Restricted说明当前用户不能运行任何脚本需要改成允许本地脚本执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned表示本地脚本可以直接运行从网上下载的脚本则要求有可信签名。这个改动只作用于当前用户不影响系统级设置风险在可控范围内。执行完之后重新打开终端再运行claude就不会被拦了。要注意的是这条命令本身也需要管理员权限吗并不需要-Scope CurrentUser限定在当前用户范围即可执行。如果你用的是公司统一管理的电脑碰到策略被组策略锁死的情况那就需要找管理员协助不要用绕过手段不然容易惹出合规问题。3. macOS 安装的相同与不同之处3.1 与 Windows 最大的区别macOS 的终端默认是 zsh文件系统的权限模型和 Windows 完全不一样。Windows 环境变量是集中管理的改完系统全局生效macOS 则是在用户主目录下的 shell 配置文件中设置通常是~/.zshrc。很多从 Windows 转到 macOS 的朋友会习惯性按照 Windows 的思路去搜教程结果发现改完配置文件不生效或者是改了错误的文件。核心逻辑其实是一样的只是入口不同Windows 找“系统属性 - 环境变量”macOS 编辑~/.zshrc然后执行source ~/.zshrc让配置生效。还有一点要注意macOS 上如果你安装的是新版 shell比如 fish那配置文件的名称和语法就是另一套了。我这里按最常见的 zsh 说明。3.2 Homebrew 和 npm 两条路怎么选macOS 用户装命令行工具第一反应通常是 Homebrew。Homebrew 的好处是路径统一、卸载方便一条brew uninstall就清理干净不用担心残留文件。前提是你已经装好了 Homebrew。没有装过的话安装 Homebrew 本身就要花一些时间期间系统还会弹窗要求安装 Xcode 命令行工具等它跑完就行。这个弹窗是正常的不用慌。我的建议是分两种情况如果你日常就在用 Homebrew 管理工具那就优先走 brew 安装如果只是为了装 Claude Code 而专门引入 Homebrew那我觉得没必要。直接用 Node.js 生态里的 npm 全局安装反而更轻量。两条路装出来的claude命令是一样的使用体验没有本质区别选顺手的即可。3.3 安装完成后的路径配置macOS 上安装完成后如果终端提示claude: command not found大概率是 PATH 不完整。用 Homebrew 安装的二进制在 Apple Silicon 芯片上默认放到/opt/homebrew/bin在 Intel 芯片上放到/usr/local/bin。用 npm 全局安装的则会进入 Node.js 的全局 bin 目录路径取决于 Node.js 的安装方式。排查时先跑一下which claude看系统能不能找到这个命令找不到就检查对应目录是否在 PATH 中。zsh 下可以在~/.zshrc里加一行 export把需要补充的目录加入 PATH然后执行source ~/.zshrc。这里有个特别容易踩的坑Apple Silicon 的 Homebrew 目录是/opt/homebrew/bin很多老教程还在写/usr/local/bin照抄的结果就是永远找不到命令。你在网上看到教程时多留个心眼先确认它是针对哪代芯片的。3.4 首次启动的安全拦截macOS 对从网上下载的程序有安全校验。你通过终端执行官方安装命令一般不会触发太严重的拦截但首次启动时系统可能会弹窗询问是否允许该工具接受网络连接选允许即可。如果你下载的是压缩包手动解压安装并且系统提示“无法打开因为来自身份不明的开发者”或“已损坏”可以在终端执行xattr -cr 解压出来的应用路径这个操作是清除文件的隔离属性相当于告诉系统跳过安全校验。我必须提醒一句只在你确认文件来源可靠时使用不要对来历不明的文件随手乱跑这条命令否则等于自己关了安全门风险很高。4. 安装完成后的配置与验证4.1 三步验证安装是否成功拿到一个新装的命令行工具我习惯按三步验证不急着进真实项目。第一步执行claude --version确认版本号正常输出。第二步在空目录里执行claude --help确认各个子命令能看到说明命令文件本身没坏。第三步建一个测试文件启动claude让它读取这个文件确认内容能正常进入上下文。前两步验证的是“装没装好”第三步验证的是“服务通没通”。很多人装完第一步成功就直接进项目结果一进对话就报网络错误那其实不是安装问题而是网络或认证问题。第三步帮你把这类问题提前暴露出来排查成本低很多。4.2 初始化项目工作区进入项目根目录之后再启动 Claude Code它一般会先扫描当前目录形成项目上下文。这一步非常关键因为它的读取范围决定了它能帮你分析到哪一层。我的建议是第一次上手时不要直接在复杂的真实项目里乱试先在小测试目录里跑一遍理解它的文件读取行为。比如它默认会不会忽略某些目录、会不会读取.gitignore规则、上下文窗口能看到多少代码。这些摸清楚之后再进入真实项目效率会高很多。项目里通常还会有配置文件用来控制工具的行为比如忽略哪些路径、选择哪个模型、允许执行哪些命令。生成配置之后记得把配置文件加入版本管理的忽略列表尤其当它可能包含本地路径或密钥信息时。4.3 密钥和登录信息的保存位置登录信息一般会放在系统用户目录下的配置目录中Windows 和 macOS 的位置不一样但原则一致不要在项目目录里硬编码密钥。如果你走 API 密钥方式可以把密钥放在环境变量里。Windows 上在 PowerShell 里临时设置$env:CLAUDE_API_KEY 你的密钥macOS 上则是在~/.zshrc里写入export CLAUDE_API_KEY你的密钥注意我是用CLAUDE_API_KEY作为占位名实际变量名请以官方文档为准。环境变量有它的加载机制修改之后要重新打开终端或者执行source ~/.zshrc变量才会进入当前进程。如果你发现明明设置了却不起作用先确认是不是没有重新加载。还有一个被我踩过多次的坑配置目录里残留了旧的登录缓存导致新密钥不生效。遇到认证问题把你认为相关的环境变量临时清掉再启动一次看看往往能找到问题所在。4.4 其他需要留意的配置项有几个配置项我建议第一次安装后就检查一遍。网络相关配置。如果你的网络环境需要使用系统层面的网络转发工具那 Claude Code 内部最好有独立的连接配置而不是依赖系统全局模式。因为全局模式可能把请求带到非预期节点表现就是“工具装了但请求偶尔超时”。建议先确认默认配置能不能稳定连通再决定要不要单独调整。命令执行权限。Claude Code 在特定场景下会建议自动执行一些命令我先把它开到“询问模式”就是每条命令执行前都问一圈。等熟悉了它的行为逻辑再逐步放宽权限避免它自作主张执行破坏性操作。更新策略。这类工具更新频率通常比较高建议每隔一段时间检查一次版本。升级前先备份配置文件特别注意配置格式有没有跨版本变化不然升完级老配置可能读不出来。5. 安装过程中最常踩的五个坑5.1 npm 全局安装时下载超时或速度极慢这个坑大概率不是 Claude Code 本身的问题而是 npm 在下载依赖时访问慢。排查链路很简单先临时安装一个无关的小包如果也慢说明是源的问题如果小包秒装那就是包体量或网络波动的偶发问题。遇到源慢可以临时切换一个延迟更低的 npm 镜像装完之后再切回默认。要注意的是第三方镜像同步可能有延迟个别依赖版本可能缺文件。所以我的习惯是镜像只用来加速安装这个动作装完立刻切回官方源避免后续使用中依赖解析异常。5.2 提示找不到 claude 命令命令找不到九成是 PATH 的问题也就是系统不知道去哪找claude可执行文件。先确认安装目录下是不是真的有可执行文件。Windows 上 npm 全局安装目录通常在用户目录下的AppData\Roaming\npmmacOS 上通常在 Node 的全局 bin 目录。找到文件之后把对应目录补充进 PATH。改完 PATH 之后Windows 要开新终端窗口macOS 要source ~/.zshrc。还有一个好用的排查工具是which claude它能告诉你当前调用的命令来自哪个路径。如果你发现明明在 A 目录装了新版which claude却指向 B 目录的旧版那就是 PATH 顺序在作怪。5.3 安装时报权限不足这类报错在 macOS 上最典型提示EACCES或者permission denied。很多人第一反应是加sudo我强烈不建议。原因很简单sudo npm install -g会以 root 身份写入全局目录后续你用普通用户执行命令时可能因权限不匹配而失败升级时更是一团乱麻。更合理的做法是把 npm 的全局安装目录指到当前用户主目录或者用 Node 版本管理器重新安装 Node从根上避免权限问题。Windows 上如果安装在 Program Files 相关目录也会出现权限错误解决办法同样是调整全局目录位置。5.4 登录成功却被提示未授权这种问题最让人恼火因为明明刚登录过却依然提示没有权限。我遇到过的原因里八成是环境变量残留或配置文件冲突。排查时按照“环境变量 工作区配置 全局配置 默认配置”的优先级逐个检查。先取消可能存在的相关环境变量再删掉项目目录内的配置文件重新启动。你可能会发现是某一个旧配置在捣乱而不是工具装坏了。如果你同时用过浏览器授权和 API 密钥两种方式也容易出现两套凭据同时存在的情况。建议只保留一种混用反而容易触发权限判断混乱。5.5 启动后请求全部超时或被拒这类问题十有八九和系统层面的网络转发设置有关。你本机开着转发工具时终端里的请求可能会被路由到非预期节点表现就是工具能启动但一发起请求就超时。排查时先把转发工具临时关闭再启动 Claude Code 测试。如果关掉之后一切正常说明需要给工具单独配置连接方式或者把目标域名加入放行列表。反过来如果你的网络环境必须借助转发才能连通服务那就需要确认本地端口、协议配置是否正确别凭感觉填先去看官方文档里的说明。另外超时问题还要区分是建立连接超时还是响应超时。前者大多是网络路径问题后者可能是服务端响应慢或请求体量太大。这两个方向别搞混不然排查半天没有结果。6. 卸载、升级与多版本管理6.1 干净卸载卸载一个 npm 全局工具很简单npm uninstall -g 官方包名。用 Homebrew 装的卸载命令是brew uninstall 包名。这是前提。但很多人忽略的是配置文件。工具运行过程中会在用户主目录下生成配置目录里面有登录缓存、日志和偏好设置。卸载命令不会清理这些残留的配置可能会影响下次重新安装。建议在卸载后找到工具自己的配置目录手动删除。Windows 上一般在当前用户的 AppData 目录下macOS 一般在~/.下具体名字以官方文档为准。清理时只删除工具自身目录不要用通配符删掉一堆无关文件。6.2 安全升级升级本身不复杂但我不建议直接上最新版。先看一眼官方更新记录确认有没有破坏性变更然后备份当前配置特别是工作区里的配置文件执行升级命令完成后验证版本号和基本功能。如果升级后出现异常第一反应不是重装而是回滚到上一个稳定版本然后对比新旧版本的配置差异看是不是某项默认行为变了。我自己经历过一次升级导致配置格式不兼容的情况回滚之后才意识到要先迁移配置再升级顺序反过来就省事了。6.3 多版本并存的经验如果你是重度使用者或者要在多个项目里测试不同版本我推荐用 Node 版本管理器做隔离。每个 Node 版本对应一套全局包切换 Node 版本时工具版本也跟着切换。这个方案适合需要频繁切换、对版本敏感的人缺点是需要额外学习和维护一套工具。如果你没有这么强的需求那就锁版本号。在项目配置里明确记录使用的工具版本升级前先在小项目测试再覆盖到复杂项目。我在实际项目里通常就是锁版本的做法配合官方更新记录足够应对大多数情况。卸载、升级、多版本管理这三件事其实反映的是同一个原则命令行工具不是一个安装完就扔那不管的东西它有自己的生命周期。养成“安装前查文档升级前看变更卸载后清残留”的习惯能省下的时间远超你的想象。最后分享一点个人体会。我在实际安装和配置 Claude Code 的过程中最大的感受是安装本身从来不复杂复杂的是把环境变量、网络连通性和认证信息这三件事同时理顺。我的习惯是第一次安装时把官方文档的安装章节保存下来然后依次检查 Node 版本、连接状态、登录信息最后才进入真实项目。这套顺序看起来慢但能把后续很多“玄学报错”摁死在发生之前。这套经验放在任何命令行工具上都适用希望对你有用。
阅读完成 · 觉得有帮助？
