常见安装问题

这一节把新手最容易踩的坑集中列出来。每个问题按现象、根因、解法三段式讲清楚，装出问题时对照排查。

先说两个万金油：claude --version 用来确认二进制装没装上；claude doctor 用来做完整环境体检，它会依次检查 Node 版本、网络连通性、代理配置、凭证有效性，报告里会明确告诉你哪里不对。装完出问题的第一反应就是这两条。

问题一：Node 版本太老

现象：跑 claude 或安装脚本时报 unsupported Node version、SyntaxError: Unexpected token '?.'、或者直接闪退。

根因：Claude Code 要求 Node.js 18 及以上。Ubuntu 20.04、Debian 10 系统源里默认的 Node 是 10 或 12，macOS 上如果长期没升过 brew，也可能停留在 16。旧版本不支持新语法和新 API，Claude Code 会直接罢工。

解法：先跑 node --version 核实。低于 18 就升级：

# 用 nvm 管理版本，推荐
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20
nvm use 20

# macOS 直接用 brew
brew install node@20

升级完再重跑 claude --version 验证。

问题二：Windows 长路径限制

现象：Windows 上装完 Claude Code，跑某些命令时报 ENAMETOOLONG 或者 The system cannot find the path specified，尤其是在深层 node_modules 里。

根因：Windows 默认路径长度上限是 260 字符，遇到深层依赖树容易超限。

解法：以管理员身份打开 PowerShell，跑一次：

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

重启电脑生效。然后再让 git 也支持长路径：

git config --global core.longpaths true

问题三：代理没生效

现象：claude 一直卡在 authenticating 或者 fetching 阶段，最后超时报 ETIMEDOUT 或 ECONNREFUSED。

根因：本机能上境外网，但 Claude Code 所在的终端没有继承代理环境变量。图形界面的代理软件不会自动写进 CMD 或 PowerShell。

解法：在启动 claude 之前手动导入环境变量：

# macOS / Linux
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

# Windows PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"

端口按你代理软件实际的 HTTP 端口填。想每次开终端自动生效，Unix 写进 ~/.zshrc，Windows 加到系统的用户环境变量里。

问题四：公司内网 SSL 证书

现象：能连到外网，但 Claude Code 报 unable to verify the first certificate 或 self signed certificate in certificate chain。

根因：公司内网通常会做 HTTPS 中间人解密，用自签的根证书替换真实证书链。Node.js 默认不信任这类根证书。

解法：拿到公司下发的根证书 PEM 文件，把路径告诉 Node：

# macOS / Linux
export NODE_EXTRA_CA_CERTS=/absolute/path/to/company-root-ca.pem

# Windows PowerShell
$env:NODE_EXTRA_CA_CERTS = "C:\certs\company-root-ca.pem"

设完重启 claude 就能过 SSL 校验。同样建议写进 shell 配置或系统环境变量。

问题五：Windows 上选哪个 shell

现象：在 CMD 里跑 claude 显示乱码、光标错位、部分快捷键失效。

根因：老 cmd.exe 不支持 ANSI 转义、Unicode 显示、真彩色，Claude Code 的 TUI 界面会严重错乱。

解法：改用现代终端。推荐组合是 Windows Terminal + PowerShell 7。装法：

winget install Microsoft.WindowsTerminal
winget install Microsoft.PowerShell

打开 Windows Terminal，把默认 profile 设成 PowerShell 7，再跑 claude 就正常了。WSL 里跑也可以，走 Linux 那套即可。

问题六：macOS Xcode 命令行工具缺失

现象：macOS 上跑 npm install 或者装某些原生依赖时报 xcrun: error: invalid active developer path。

根因：Claude Code 在项目里跑 npm install 时，如果依赖需要编译原生模块，会用到 Apple 的 Xcode Command Line Tools。系统升级或者第一次用开发环境时它可能缺失。

解法：一条命令装上：

xcode-select --install

会弹一个系统对话框，点安装，等几分钟装完。装完再回到 Claude Code 会话里重试。

问题七：读 claude --version 输出

现象：不确定装的是不是最新版，或者升级完不确定生效没。

解法：claude --version 输出格式是 claude 1.x.y (Claude Code)。前面的版本号是 CLI 版本，跟着 Claude Code 迭代更新。想看更详细信息，跑：

claude doctor

它会打印 Node 版本、CLI 版本、认证状态、网络连通性等一整套体检报告。如果某项显示红色或者 warning，按提示动作。

问题八：claude doctor 深入排错

claude doctor 是新手最应该记住的命令。装完想验证：跑一遍看全绿。装完出问题：跑一遍看它红在哪。升级前后想确认：跑一遍对比。它会输出类似这样的内容：

Node.js version: v20.11.1  ok
Claude Code CLI: 1.0.x     ok
Auth status: signed in as x@example.com  ok
Network: reachable         ok

任何一项非 ok，往上翻本页对应的问题条目，八成能对号入座。

实在解决不了

如果对着排错手册也搞不定，可以带上 claude doctor 完整输出去 Anthropic Discord 或 GitHub Issues 求助，比只描述现象效率高十倍。也可以把出错时的完整终端输出贴到求助帖里，尤其是首行的错误码，比如 ETIMEDOUT、ENOENT，社区一眼就能识别是哪类问题。