最近后台和社群里被问得最多的一个问题基本长这样装 Claude Code 装到一半卡住或者装完了在终端里敲claude没有任何反应再或者是折腾完配置文件之后启动还是转圈。我把这些聊天记录翻出来对照了一下发现一个共同点——大多数人不是某个环节的具体操作不会而是把顺序搞反了。Claude Code 在 Windows、macOS、Linux 三个平台上的坑还不一样你拿 A 平台的教程去套 B 平台很容易越折腾越乱。这篇文章就是我从实际排查里整理出来的完整跑通路线按安装、配置文件、首次启动三个阶段拆开每个阶段该做什么、该看什么输出、卡住之后怎么判断最后附上我真实排过的三个卡点案例。准备装或者已经卡住的朋友都建议从头到尾顺着过一遍很多问题其实不是你操作的问题而是阶段顺序没理顺。1. 先定位你卡在哪一步安装、文件、启动三个阶段怎么分1.1 三个阶段的判断信号Claude Code 从零到能用的过程其实就三步把程序装到机器里、确认配置被正确放置、启动时完成认证和会话。这三步是严格串行的前一步没完成后一步表现出的症状会非常迷惑。我见过太多人卡在启动阶段结果查了半天发现是安装阶段的 PATH 没配好——这种问题不按阶段来永远定位不出来。先把三个阶段的信号列出来你可以自己对号入座。阶段你执行的操作正常应该看到的反馈常见的卡住表现安装npm install -g anthropic-ai/claude-code命令结束前看到 added XXX packages耗时几十秒到几分钟不等进度条长时间不动、报 EACCES/EPERM、提示网络错误文件创建或编辑~/.claude下的配置文件文件正常保存重新打开内容还在无乱码配置保存了但启动完全不生效或启动直接报 JSON 解析错误启动在终端执行claude进入交互界面首次使用有认证提示之后能看到模型回复黑屏无输出、反复跳认证页、启动后立刻退出判断方法很简单你最后一次动手是在哪个阶段就先解决那个阶段的问题不要跳到后面去。比如安装命令都还没跑成功就不要先去研究 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 命令会消失。LinuxUbuntu/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或者用管理员权限的 PowerShellWindows。全局安装确实需要写目录的权限但用 sudo 或管理员方式装出来的结果目录所有权会变成 root 或管理员账号后面你自己在用户态去更新、去读配置文件会连锁出一堆授权问题。正确做法是让 npm 的全局目录落在你的用户目录下。可以先看一下当前配置npm config get prefixmacOS/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\npmmacOS/Linux 加 PATH 的方式上一条已经写过。改完 PATH 后重启终端再试claude --version。如果这条命令输出版本号了说明安装阶段正式跑通可以进入下一个阶段。3. 配置文件阶段路径、字段、权限一个都不能错3.1 用户级配置与项目级配置的位置安装阶段跑通之后很多人会直接敲claude然后卡在认证或者各种行为异常上。这是因为你不清楚 Claude Code 会从哪里读配置。它的配置分两层用户级和项目级。用户级配置放在主目录下的.claude目录中主文件是settings.json。具体路径取决于系统WindowsC:\Users\你的用户名\.claude\settings.jsonmacOS/Users/你的用户名/.claude/settings.jsonLinux/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 按 CmdShift. 快捷键显示隐藏文件Linux 终端直接ls -a就能看到。终端里查看配置是否就位ls -la ~/.claude/macOS/Linux 下还要注意目录所有权。如果你前面安装时用了 sudo或者把整个主目录的所有权改乱过.claude目录可能是 root 所有当前用户无法写入。表现就是工具想写会话记录、历史文件时一直被拒绝或者启动后行为异常。修复命令chown -R 你的用户名 ~/.claudeWindows 上如果遇到类似问题检查目录是否被只读标记或者在目录安全属性里给当前用户完全控制权限。还有一个实操建议修改配置文件之前先复制一份备份比如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 启动后卡住或反复认证的定位思路环境变量和配置都对但启动还是卡可以通过下表快速定位表现优先怀疑的方向对应检查卡在认证等待页面浏览器登录流程没走完或凭证写入失败检查凭证目录是否有写入权限重跑登录流程启动后立刻退出配置文件 JSON 报错用 JSON 校验工具检查 settings.json反复要求输入 API Key环境变量没注入当前 shell执行echo $env:ANTHROPIC_API_KEYPowerShell或echo $ANTHROPIC_API_KEYbash确认光标在黑屏闪烁无输出Node 版本过老或安装目录被破坏重跑claude --version考虑升级 Node 后重新安装中文显示乱码Windows 终端编码问题PowerShell 里执行chcp 65001切换到 UTF-8环境变量的检查是最容易忽略的。在同一个终端里执行下面两条先确认当前 shell 真的能读到变量再去排查别的PowerShell:echo $env:ANTHROPIC_API_KEYbash/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 或 bashWindows 统一用 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 的树形加载阶段等了两分钟没有任何变化。当时我这个案例的关键教训是安装卡住时先分清楚是整个流程就没开始还是下载过程慢。前者多半是版本或环境问题后者多半是网络源问题。排查过程是这样的按 CtrlC 终止安装先执行node -v和npm -v确认版本分别是什么。结果 Node 是 v16、npm 是 8版本明显偏旧。把 Node 升级到 18 LTS重新打开终端再次执行安装命令。这次进度条依然慢但能看出是在下载依赖而不是死等。为了提速切到镜像源命令很快跑完出现 added 237 packages 之类的结果。在进度条完全不动的情况下CtrlC 之后先检查版本再聊别的这个顺序最省时间。如果版本没问题再看源和网络不要一上来就反复重试。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 无 BOMJSON 校验通过目录属主是当前用户启动阶段三连当前 shell 能读到ANTHROPIC_API_KEY或已经完成过一次登录终端是新开的或者已经 source 过配置用claude --version确认可执行文件路径正确这三个三连对应十分钟的排查时间。我自己把它写成了一个 shell 函数放在机器上每次准备启动 claude 前先跑一遍确认环境没问题再进交互界面。这个习惯看起来多了一步实际上省掉了无数次怎么又卡了的排查过程。踩过几次坑之后我最大的体会是这类工具装不上大多数时候不是工具本身的问题而是环境顺序的问题。Node 装没装、PATH 对不对、配置文件合不合法、环境变量有没有进当前 shell这四件事顺着过一遍几乎所有卡住的情况都能自己解决。 
长河君 · 2026/9/15 3:20:46 · 阅读 1.2k Claude Code三平台安装配置全攻略：从卡住到跑通
最近后台和社群里被问得最多的一个问题基本长这样装 Claude Code 装到一半卡住或者装完了在终端里敲claude没有任何反应再或者是折腾完配置文件之后启动还是转圈。我把这些聊天记录翻出来对照了一下发现一个共同点——大多数人不是某个环节的具体操作不会而是把顺序搞反了。Claude Code 在 Windows、macOS、Linux 三个平台上的坑还不一样你拿 A 平台的教程去套 B 平台很容易越折腾越乱。这篇文章就是我从实际排查里整理出来的完整跑通路线按安装、配置文件、首次启动三个阶段拆开每个阶段该做什么、该看什么输出、卡住之后怎么判断最后附上我真实排过的三个卡点案例。准备装或者已经卡住的朋友都建议从头到尾顺着过一遍很多问题其实不是你操作的问题而是阶段顺序没理顺。1. 先定位你卡在哪一步安装、文件、启动三个阶段怎么分1.1 三个阶段的判断信号Claude Code 从零到能用的过程其实就三步把程序装到机器里、确认配置被正确放置、启动时完成认证和会话。这三步是严格串行的前一步没完成后一步表现出的症状会非常迷惑。我见过太多人卡在启动阶段结果查了半天发现是安装阶段的 PATH 没配好——这种问题不按阶段来永远定位不出来。先把三个阶段的信号列出来你可以自己对号入座。阶段你执行的操作正常应该看到的反馈常见的卡住表现安装npm install -g anthropic-ai/claude-code命令结束前看到 added XXX packages耗时几十秒到几分钟不等进度条长时间不动、报 EACCES/EPERM、提示网络错误文件创建或编辑~/.claude下的配置文件文件正常保存重新打开内容还在无乱码配置保存了但启动完全不生效或启动直接报 JSON 解析错误启动在终端执行claude进入交互界面首次使用有认证提示之后能看到模型回复黑屏无输出、反复跳认证页、启动后立刻退出判断方法很简单你最后一次动手是在哪个阶段就先解决那个阶段的问题不要跳到后面去。比如安装命令都还没跑成功就不要先去研究 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 命令会消失。LinuxUbuntu/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或者用管理员权限的 PowerShellWindows。全局安装确实需要写目录的权限但用 sudo 或管理员方式装出来的结果目录所有权会变成 root 或管理员账号后面你自己在用户态去更新、去读配置文件会连锁出一堆授权问题。正确做法是让 npm 的全局目录落在你的用户目录下。可以先看一下当前配置npm config get prefixmacOS/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\npmmacOS/Linux 加 PATH 的方式上一条已经写过。改完 PATH 后重启终端再试claude --version。如果这条命令输出版本号了说明安装阶段正式跑通可以进入下一个阶段。3. 配置文件阶段路径、字段、权限一个都不能错3.1 用户级配置与项目级配置的位置安装阶段跑通之后很多人会直接敲claude然后卡在认证或者各种行为异常上。这是因为你不清楚 Claude Code 会从哪里读配置。它的配置分两层用户级和项目级。用户级配置放在主目录下的.claude目录中主文件是settings.json。具体路径取决于系统WindowsC:\Users\你的用户名\.claude\settings.jsonmacOS/Users/你的用户名/.claude/settings.jsonLinux/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 按 CmdShift. 快捷键显示隐藏文件Linux 终端直接ls -a就能看到。终端里查看配置是否就位ls -la ~/.claude/macOS/Linux 下还要注意目录所有权。如果你前面安装时用了 sudo或者把整个主目录的所有权改乱过.claude目录可能是 root 所有当前用户无法写入。表现就是工具想写会话记录、历史文件时一直被拒绝或者启动后行为异常。修复命令chown -R 你的用户名 ~/.claudeWindows 上如果遇到类似问题检查目录是否被只读标记或者在目录安全属性里给当前用户完全控制权限。还有一个实操建议修改配置文件之前先复制一份备份比如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 启动后卡住或反复认证的定位思路环境变量和配置都对但启动还是卡可以通过下表快速定位表现优先怀疑的方向对应检查卡在认证等待页面浏览器登录流程没走完或凭证写入失败检查凭证目录是否有写入权限重跑登录流程启动后立刻退出配置文件 JSON 报错用 JSON 校验工具检查 settings.json反复要求输入 API Key环境变量没注入当前 shell执行echo $env:ANTHROPIC_API_KEYPowerShell或echo $ANTHROPIC_API_KEYbash确认光标在黑屏闪烁无输出Node 版本过老或安装目录被破坏重跑claude --version考虑升级 Node 后重新安装中文显示乱码Windows 终端编码问题PowerShell 里执行chcp 65001切换到 UTF-8环境变量的检查是最容易忽略的。在同一个终端里执行下面两条先确认当前 shell 真的能读到变量再去排查别的PowerShell:echo $env:ANTHROPIC_API_KEYbash/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 或 bashWindows 统一用 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 的树形加载阶段等了两分钟没有任何变化。当时我这个案例的关键教训是安装卡住时先分清楚是整个流程就没开始还是下载过程慢。前者多半是版本或环境问题后者多半是网络源问题。排查过程是这样的按 CtrlC 终止安装先执行node -v和npm -v确认版本分别是什么。结果 Node 是 v16、npm 是 8版本明显偏旧。把 Node 升级到 18 LTS重新打开终端再次执行安装命令。这次进度条依然慢但能看出是在下载依赖而不是死等。为了提速切到镜像源命令很快跑完出现 added 237 packages 之类的结果。在进度条完全不动的情况下CtrlC 之后先检查版本再聊别的这个顺序最省时间。如果版本没问题再看源和网络不要一上来就反复重试。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 无 BOMJSON 校验通过目录属主是当前用户启动阶段三连当前 shell 能读到ANTHROPIC_API_KEY或已经完成过一次登录终端是新开的或者已经 source 过配置用claude --version确认可执行文件路径正确这三个三连对应十分钟的排查时间。我自己把它写成了一个 shell 函数放在机器上每次准备启动 claude 前先跑一遍确认环境没问题再进交互界面。这个习惯看起来多了一步实际上省掉了无数次怎么又卡了的排查过程。踩过几次坑之后我最大的体会是这类工具装不上大多数时候不是工具本身的问题而是环境顺序的问题。Node 装没装、PATH 对不对、配置文件合不合法、环境变量有没有进当前 shell这四件事顺着过一遍几乎所有卡住的情况都能自己解决。