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 默认的终端是 PowerShell，macOS 默认是 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 或 11，macOS 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\npm，macOS 上通常在 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 版本、连接状态、登录信息，最后才进入真实项目。这套顺序看起来慢，但能把后续很多“玄学报错”摁死在发生之前。这套经验放在任何命令行工具上都适用，希望对你有用。
