Claude Code三平台安装配置全攻略：从卡住到跑通

最近后台和社群里被问得最多的一个问题，基本长这样：装 Claude Code 装到一半卡住，或者装完了在终端里敲claude没有任何反应，再或者是折腾完配置文件之后启动还是转圈。我把这些聊天记录翻出来对照了一下，发现一个共同点——大多数人不是某个环节的具体操作不会，而是把顺序搞反了。Claude Code 在 Windows、macOS、Linux 三个平台上的坑还不一样，你拿 A 平台的教程去套 B 平台，很容易越折腾越乱。

这篇文章就是我从实际排查里整理出来的完整跑通路线：按安装、配置文件、首次启动三个阶段拆开，每个阶段该做什么、该看什么输出、卡住之后怎么判断，最后附上我真实排过的三个卡点案例。准备装或者已经卡住的朋友，都建议从头到尾顺着过一遍，很多问题其实不是你操作的问题，而是阶段顺序没理顺。

1. 先定位你卡在哪一步：安装、文件、启动三个阶段怎么分

1.1 三个阶段的判断信号

Claude Code 从零到能用的过程，其实就三步：把程序装到机器里、确认配置被正确放置、启动时完成认证和会话。这三步是严格串行的，前一步没完成，后一步表现出的症状会非常迷惑。我见过太多人卡在启动阶段，结果查了半天发现是安装阶段的 PATH 没配好——这种问题不按阶段来，永远定位不出来。

先把三个阶段的信号列出来，你可以自己对号入座。

判断方法很简单：你最后一次动手是在哪个阶段，就先解决那个阶段的问题，不要跳到后面去。比如安装命令都还没跑成功，就不要先去研究 settings.json 里怎么写权限，那是后面的事。

1.2 三个阶段的依赖关系

为什么要强调顺序？因为这三个阶段之间是环环相扣的依赖关系。

安装阶段解决的是"有没有 claude 这个命令"的问题。这一步没做对，后续所有配置文件都是空中楼阁，你连claude都敲不出来。配置文件阶段解决的是"程序怎么知道你是谁、允许做什么"的问题，它是程序启动之后要读取的关键信息。启动阶段解决的是"认证怎么过、环境变量怎么注入"的问题。一旦你在安装阶段就跳过了 PATH 设置，在启动阶段就会看到claude: command not found，但这个时候你大概率会去搜"claude 启动不了"，然后被各种无关教程带到更深的坑里。

反过来也一样。配置文件阶段如果 JSON 写错了，启动时可能看到工具立刻退出或者行为怪异，但报错信息里可能根本不会告诉你"是配置文件的第几行出了错"，你会以为是自己启动姿势不对。所以按顺序排查，是效率最高的一条路。

1.3 一条命令序列，三平台通用

先把完整的最小命令序列放在这，Windows 在 PowerShell 里执行，macOS/Linux 在终端里执行，命令几乎一样：

node -v npm -v npm install -g @anthropic-ai/claude-code claude --version claude

如果你的环境很干净，这五条命令按顺序跑完就能进交互界面。凡是卡住的，基本都是这五条里的某一条没有达到预期结果。后面几个章节，我把每一条拆开讲，包括不同系统环境下会出现的变体情况。

2. 安装阶段：Node 版本、npm 源与三平台的权限差异

2.1 先确认 Node.js 版本：低了真的装不上

Claude Code 是用 Node.js 写的命令行工具，通过 npm 分发，所以机器上必须先有 Node.js 和 npm。很多人在这一步就出问题了，但不是因为没装，而是因为版本太老。

我遇到过最小号的坑：一台旧 Windows 机器上装的是 Node 14，跑安装命令时 npm 直接报错，提示某个依赖版本不支持当前的 Node。Claude Code 对 Node 版本有最低要求，一般建议至少 Node 18 以上，低于这个版本会出现各种奇怪的安装失败。检查方式：

node -v npm -v

如果node -v提示 command not found，说明 Node 压根没装；如果版本号是 v16 或者更老，建议直接升级到 LTS 版本，不要想着"先装上去再说"，后面启动阶段会让你更痛苦。

Node.js 的安装方式，我按平台给三个推荐：

• Windows：去官网下载 LTS 版本的 MSI 安装包，一路下一步；或者用 nvm-windows 管理多版本，适合需要来回切版本的场景。
• macOS：如果只是要一个能用的环境，Homebrew 装是最快的：

  brew install node

  如果想多版本切换，用 nvm。注意 nvm 需要按照官方说明把初始化脚本写进~/.zshrc或~/.bashrc，否则重启终端后 nvm 命令会消失。
• Linux：Ubuntu/Debian 系系统 apt 里的 Node 版本普遍偏旧，我更推荐用 nvm 安装，而不是直接apt install nodejs。如果一定要用 apt，装完检查版本，老版本再想升级会非常麻烦。

装完 Node 之后，不要急着重开十次终端，先确认 node 和 npm 都可用，再继续往下走。

2.2 npm 全局安装命令与权限问题

装 Claude Code 的命令是一行：

npm install -g @anthropic-ai/claude-code

注意-g表示全局安装。新手最容易犯的错误是用 sudo 执行这条命令（macOS/Linux），或者用管理员权限的 PowerShell（Windows）。全局安装确实需要写目录的权限，但用 sudo 或管理员方式装出来的结果，目录所有权会变成 root 或管理员账号，后面你自己在用户态去更新、去读配置文件，会连锁出一堆授权问题。

正确做法是让 npm 的全局目录落在你的用户目录下。可以先看一下当前配置：

npm config get prefix

macOS/Linux 下，如果 prefix 是/usr或/usr/local这类系统目录，而你又是普通用户，安装时大概率会遇到 EACCES 权限错误。这时不要去 sudo，改成把全局目录改到用户目录：

npm config set prefix ~/.npm-global

然后在 shell 配置文件（~/.zshrc或~/.bashrc）里加上：

export PATH=~/.npm-global/bin:$PATH

最后 source 一下或者重开终端。

Windows 的情况略有不同。如果你用默认的 Node MSI 安装，npm 全局目录一般在%APPDATA%\npm。安装时如果遇到 EPERM 错误，先检查这个目录是不是被安全软件锁定，或者试试在"设置 -> 隐私和安全性 -> 开发者选项"里打开"开发人员模式"，可以缓解部分目录权限问题。不建议开管理员终端硬刚，后续隐藏坑太多。

2.3 npm 下载慢时的镜像源调整

如果你发现安装命令卡在下载依赖这一步，npm 进度条在原地不动，或者提示 ETIMEDOUT、ENOTFOUND 这类网络错误，十有八九是访问官方源的速度不理想。这时候可以临时切到镜像源加速。

npm config set registry https://registry.npmmirror.com

切换后执行npm config get registry确认一下，再重新运行安装命令。等安装完成后，如果想恢复默认源：

npm config set registry https://registry.npmjs.org

这个做法只是把下载源换成了国内镜像，不改变任何功能行为。注意这是下载源，不是网络配置，别把概念搞混。

2.4 安装成功后的验证标准

安装成功的标志不是"屏幕上没有报错"，而是这条命令能正常输出版本号：

claude --version

如果提示 command not found，不要慌，十个里有九个是 PATH 没生效，也就是 npm 的全局 bin 目录没有被当前终端识别。先找到 npm 全局 bin 的实际位置：

npm prefix -g

以这个命令的输出为基准，把这个目录加到 PATH 里。Windows 用户在 PowerShell 里可以这样临时设置：

$env:Path += ";$env:APPDATA\npm"

macOS/Linux 加 PATH 的方式上一条已经写过。改完 PATH 后，重启终端再试claude --version。如果这条命令输出版本号了，说明安装阶段正式跑通，可以进入下一个阶段。

3. 配置文件阶段：路径、字段、权限，一个都不能错

3.1 用户级配置与项目级配置的位置

安装阶段跑通之后，很多人会直接敲claude，然后卡在认证或者各种行为异常上。这是因为你不清楚 Claude Code 会从哪里读配置。它的配置分两层：用户级和项目级。

用户级配置放在主目录下的.claude目录中，主文件是settings.json。具体路径取决于系统：

• Windows：C:\Users\你的用户名\.claude\settings.json
• macOS：/Users/你的用户名/.claude/settings.json
• Linux：/home/你的用户名/.claude/settings.json

另外可以用环境变量CLAUDE_CONFIG_DIR改变这个目录的位置。如果机器上多个工具共用同一套目录导致冲突，可以给 Claude Code 单独指定一个目录。

项目级配置放在当前工作目录下的.claude子目录里，路径是.claude/settings.json。它的作用是让不同项目拥有不同的权限策略和模型选择，适合团队协作时把允许执行的命令写进项目提交到版本库。

两个层级的配置会合并生效，项目级优先级高于用户级。

3.2 配置字段和写错之后的表现

settings.json 是一个 JSON 文件，我日常用的结构大致是这样：

{ "permissions": { "allow": ["Read", "Edit", "Bash"], "deny": [] }, "model": "claude-sonnet-4-5", "env": { "TIMEOUT_MS": "60000" } }

permissions 控制这个工具在项目里能做什么，allow 列表放你允许的操作类别，deny 列表放禁止的操作。model 字段指定使用的模型名称。env 字段可以注入会话里需要的环境变量。具体的字段组织形式以你安装的版本为准，这里展示的是我常用到的结构。

字段写错通常有三种表现。

第一种是 JSON 语法错误。比如末尾多了一个逗号，或者字符串引号没有闭合。工具启动时读配置文件失败，表现可能是立刻退出，也可能是卡在初始化界面不动，报错信息里通常带有 JSON 或者 parse 字样。

第二种是字段名写错。比如把 permissions 写成了 permission，工具不会报错，但文件完全不生效，你授权的东西用不了，想禁用的禁不掉。这种最坑，因为没有任何提示。

第三种是 Windows 上的编码问题。某些编辑工具保存文件时默认用带 BOM 的 UTF-8，或者用 GBK 编码，JSON 解析器可能不认。在 Windows 下编辑配置文件，记得在编辑器右下角把编码切到 UTF-8（不带 BOM）。

3.3 隐藏目录的查看方式和文件权限

.claude目录是隐藏目录，在文件管理器里默认看不到。Windows 的资源管理器需要在"查看"里勾选"隐藏的项目"，macOS 的 Finder 按 Cmd+Shift+. 快捷键显示隐藏文件，Linux 终端直接ls -a就能看到。

终端里查看配置是否就位：

ls -la ~/.claude/

macOS/Linux 下还要注意目录所有权。如果你前面安装时用了 sudo，或者把整个主目录的所有权改乱过，.claude目录可能是 root 所有，当前用户无法写入。表现就是工具想写会话记录、历史文件时一直被拒绝，或者启动后行为异常。修复命令：

chown -R 你的用户名 ~/.claude

Windows 上如果遇到类似问题，检查目录是否被"只读"标记，或者在目录安全属性里给当前用户完全控制权限。

还有一个实操建议：修改配置文件之前，先复制一份备份，比如settings.json.bak。这个工具跑起来后会持续写会话历史文件，你一边改配置它一边写文件，一旦保存出错，连排查的日志都没了。备份能让你随时回滚。

4. 启动阶段：认证方式、环境变量注入与首次会话

4.1 首次启动必须完成的认证

配置检查完，再执行claude命令。第一次进入时，你会看到一个认证引导，一般会让你选一种认证方式：用 Anthropic 账号登录，或者粘贴 API Key。

我推荐第一次用浏览器登录的方式，它会打开一个浏览器页面，你登录账号后，页面会给出一段授权码，把授权码粘回终端，认证就算完成。整个流程看起来多，实际上就一两分钟。

如果浏览器没有自动打开，检查终端是否支持打开外部链接，或者手动复制终端输出的链接到浏览器。有时终端复制不方便，可以先记录链接地址再粘贴。

如果选择 API Key 方式，就需要把ANTHROPIC_API_KEY环境变量设置好再启动，设置方式后面会说。

认证完成之后，工具会把凭证信息存储在本地的配置目录里，下次启动不需要重新认证。这一步如果一直卡在等待页面，优先往"凭证写入失败"这个方向查，而不是反复重跑登录。

4.2 环境变量的注入：PowerShell、CMD、bash 的区别

API Key 和自定义配置都要通过环境变量注入。这里特别容易踩坑：三个平台的 shell 语法不同。

macOS/Linux 的 bash/zsh，编辑~/.zshrc或~/.bashrc，加入：

export ANTHROPIC_API_KEY="你的Key"

然后source ~/.zshrc或重启终端。注意 export 只在当前 shell 会话生效，所以必须写入配置文件，而不是只在命令行临时敲。

Windows PowerShell 里，临时设置用：

$env:ANTHROPIC_API_KEY = "你的Key"

永久设置用：

setx ANTHROPIC_API_KEY "你的Key"

注意 setx 设置的环境变量不会在当前窗口生效，必须新开一个终端窗口才能读到。很多人设置完 API Key 之后在同一个窗口里跑 claude，发现没反应，就是这个原因。

CMD 的话，临时设置是set ANTHROPIC_API_KEY=你的Key，但我不建议在 CMD 里跑这种交互式工具，后面会专门说终端选择问题。

另一个常见环境变量是CLAUDE_CONFIG_DIR，如果要指定配置目录，也要在同一个配置文件里设置。

4.3 启动后卡住或反复认证的定位思路

环境变量和配置都对，但启动还是卡，可以通过下表快速定位：

环境变量的检查是最容易忽略的。在同一个终端里执行下面两条，先确认当前 shell 真的能读到变量，再去排查别的：

PowerShell:

echo $env:ANTHROPIC_API_KEY

bash/zsh:

echo $ANTHROPIC_API_KEY

如果输出为空，说明变量根本没进到当前 shell，要么重开终端，要么重新 source 配置文件。

5. 三平台终端差异与 Claude Code 的更新问题

5.1 终端选择影响的不只是外观

很多人以为终端只是输入命令的地方，选什么无所谓，但在 Windows 上这个区别挺大的。

我建议 Windows 用户用 Windows Terminal 配套 PowerShell，或者 Git Bash。尽量不要在老的 CMD 里跑这个工具的交互界面。原因有几个：一是 CMD 对 UTF-8 字符支持不理想，工具输出内容可能乱码；二是交互式界面在 CMD 下的渲染经常出问题，比如快捷键失效、输出闪烁、光标错位；三是环境变量语法不同，容易混淆。

如果你在 PowerShell 里用一段命令，bash 下又用另一段命令，时间长了容易记混。我的习惯是：macOS 和 Linux 统一用 zsh 或 bash，Windows 统一用 Windows Terminal + PowerShell。这样全平台只记两套命令，逻辑简单很多。

5.2 PATH 在你重启终端之前都是假的

命令行工具的经典场景是"我明明装好了，为什么重启后没了"。实际上很多启动阶段的问题，本质就是 PATH 没有正确加载。

在 bash/zsh 下，检查你的命令到底从哪里来：

which node which npm which claude

在 PowerShell 下：

Get-Command node Get-Command npm Get-Command claude

输出的路径应该指向同一个 Node 安装位置。如果 node 在/usr/bin，而 claude 在~/.npm-global/bin，两个路径可能不在同一个 PATH 覆盖范围内，需要把~/.npm-global/bin加进 PATH。

特别注意 nvm 场景：如果 node 是 nvm 装的，重启终端后 nvm 的初始化代码没执行，你会看到 node command not found，但工具本身在 nvm 的某个版本目录里也存在。这种问题不是重新安装能解决的，而是 nvm 初始化脚本的问题，先去检查~/.zshrc或~/.bashrc里有没有 nvm 那段初始化。

5.3 更新 Claude Code 时卡住的处理

工具迭代快，更新频繁。日常更新用：

claude --update

如果不是最新版，这条命令会拉取新版本并替换。它卡住常见于两种情况。

第一种是 Windows 上文件被占用。工具正在运行时你是没法替换主程序的，因为可执行文件被进程锁住。处理方法：彻底关掉所有和 claude 相关的终端窗口，再重新打开一个新终端执行更新。

第二种是 npm 缓存异常。如果更新过程中反复在同一个依赖上失败，可以清理 npm 缓存再重装：

npm cache clean --force npm install -g @anthropic-ai/claude-code

如果用 npx 临时跑过这个工具，注意 npx 的模式和全局安装是两套。npx 每次会临时拉取一个版本到缓存目录运行，不占用全局路径，用 npx 跑通了不代表全局安装成功。建议只走一条路：要么全局 npm install，要么明确知道自己在用 npx，别混着用，否则版本不一致很容易让你怀疑人生。

6. 踩坑实录：三次"卡住"的完整排查链路

6.1 卡点一：npm 安装进度条原地不动

事情发生在一台 Windows 11 的机器上。执行npm install -g @anthropic-ai/claude-code后，进度条停在 idealTree 的树形加载阶段，等了两分钟没有任何变化。当时我这个案例的关键教训是：安装卡住时，先分清楚是"整个流程就没开始"还是"下载过程慢"。前者多半是版本或环境问题，后者多半是网络源问题。

排查过程是这样的：

1. 按 Ctrl+C 终止安装，先执行node -v和npm -v，确认版本分别是什么。结果 Node 是 v16、npm 是 8，版本明显偏旧。
2. 把 Node 升级到 18 LTS，重新打开终端，再次执行安装命令。这次进度条依然慢，但能看出是在下载依赖，而不是死等。
3. 为了提速，切到镜像源，命令很快跑完，出现 added 237 packages 之类的结果。

在进度条完全不动的情况下，Ctrl+C 之后先检查版本，再聊别的，这个顺序最省时间。如果版本没问题，再看源和网络，不要一上来就反复重试。

6.2 卡点二：首次登录授权码回填不了

另一台 macOS 上，claude 启动后浏览器成功打开，账号也登录了，页面给出了授权码，但往终端粘贴授权码后没有任何反应，终端一直停在等待状态。

排查链路是这样：先看终端是不是还在等待输入。如果终端没有响应键盘输入，可能是终端焦点或者渲染问题，先在终端里随便按一下回车看看有没有反应，没有反应就直接用另一个终端窗口重新跑 claude。重新进入后，授权码那条交互链路会重新走一遍，这时能确认问题是不是偶发。

接着检查本地凭证目录是否可写。如果凭证写入失败，认证流程会卡在"等待写入"这一环，表现也是无响应。用ls -la ~/.claude看目录的权限和属主，确认当前用户有写权限。macOS 上如果目录是 root 属主，chown 之后重新认证即可。

最后，如果以上都没问题，就把浏览器登录方式换成 API Key 方式，跳过浏览器回填这个环节。设置好ANTHROPIC_API_KEY环境变量，新开终端，直接启动。这套方案也能绕开浏览器和终端交互的各种兼容问题。

6.3 卡点三：昨天还能用，今天启动就退出

Linux 机器上出现的情况最邪门：前一天还用得好好的，第二天 claude 一启动就退出，没有报错，输出只有两行路径信息。

第一反应是检查配置。先用编辑器打开~/.claude/settings.json，发现文件里多了一个悬空的逗号——昨天手改配置时保存了错误的内容。用 node 快速验证 JSON 合法性：

node -e "JSON.parse(require('fs').readFileSync(process.env.HOME + '/.claude/settings.json', 'utf8')); console.log('ok')"

执行后果然抛出解析异常。把配置备份到 settings.json.bak，修正 JSON 语法，再执行上面的校验命令，直到输出 ok，然后重新启动 claude，恢复正常。

这个案例说明两个问题：一是 JSON 语法错误未必有明确报错，有时候工具的启动失败信息非常弱；二是"昨天能用今天不能用"大概率是最近改动导致的，优先检查最近动过的文件，而不是怀疑系统变化。排查顺序应该是先看配置，再查日志，最后才考虑重新安装。

7. 让下次不再卡：三平台通用的一键检查清单

最后整理一份我自己的启动前检查清单，每次遇到卡住都按这个顺序过。

安装阶段三连：

• node -v不低于需要的版本
• npm -v正常输出
• npm prefix -g指向的全局 bin 目录在 PATH 里

文件阶段三连：

• ~/.claude/settings.json存在，且编码是 UTF-8 无 BOM
• JSON 校验通过
• 目录属主是当前用户

启动阶段三连：

• 当前 shell 能读到ANTHROPIC_API_KEY，或已经完成过一次登录
• 终端是新开的，或者已经 source 过配置
• 用claude --version确认可执行文件路径正确

这三个三连，对应十分钟的排查时间。我自己把它写成了一个 shell 函数放在机器上，每次准备启动 claude 前先跑一遍，确认环境没问题再进交互界面。这个习惯看起来多了一步，实际上省掉了无数次"怎么又卡了"的排查过程。

踩过几次坑之后我最大的体会是，这类工具装不上，大多数时候不是工具本身的问题，而是环境顺序的问题。Node 装没装、PATH 对不对、配置文件合不合法、环境变量有没有进当前 shell，这四件事顺着过一遍，几乎所有卡住的情况都能自己解决。