macOS 常见安装问题

本页面收集了 macOS 系统上安装 Claude Code 时的常见问题和解决方案。

Node.js 安装问题

问题：Homebrew 安装 Node.js 失败

症状： 运行 brew install node 时出错。

解决方案：

1. 更新 Homebrew：

   brew update
   brew upgrade

2. 检查 Homebrew 诊断：

   brew doctor

3. 按照提示修复问题

问题：从官网下载的安装包无法打开

症状： 双击 .pkg 文件提示 "无法打开，因为它来自身份不明的开发者"。

解决方案：

1. 打开系统偏好设置 → 安全性与隐私
2. 在"通用"标签页中，点击"仍要打开"
3. 或者右键点击安装包，选择"打开"

问题：node 命令无法识别

症状： 在 Terminal 中输入 node --version 提示 "command not found"。

解决方案：

1. 重启 Terminal
2. 检查 PATH 环境变量：

   echo $PATH

3. 手动添加 Node.js 路径到 shell 配置文件

Claude Code 安装问题

问题：npm 全局安装权限错误

症状： 运行 npm install -g 时提示 "EACCES: permission denied"。

解决方案：

1. 使用 sudo 安装：

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

2. 或者修复 npm 权限（推荐）：

   sudo chown -R $(whoami) ~/.npm
   sudo chown -R $(whoami) /usr/local/lib/node_modules

问题：安装速度很慢或超时

症状： npm 安装过程卡住或报网络错误。

解决方案：

1. 切换 npm 镜像源：

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

2. 检查网络连接
3. 重试安装命令

问题：Apple Silicon (M1/M2/M3) 兼容性问题

症状： 在 Apple Silicon Mac 上安装失败。

解决方案：

1. 确保安装的是 ARM64 版本的 Node.js
2. 检查 Node.js 架构：

   node -p "process.arch"

3. 如果显示 "x64"，重新安装 ARM64 版本

问题：claude 命令无法识别

症状： 安装成功后，输入 claude --version 提示 "command not found"。

解决方案：

1. 重启 Terminal
2. 检查全局 npm 包路径：

   npm config get prefix

3. 确认路径在 PATH 中：

   echo $PATH | grep $(npm config get prefix)

环境变量问题

问题：环境变量设置后不生效

症状： 添加到 .zshrc 或 .bash_profile 的环境变量不生效。

解决方案：

1. 确保编辑的是正确的配置文件：
   • zsh: ~/.zshrc
   • bash: ~/.bash_profile 或 ~/.bashrc
2. 重新加载配置文件：

   source ~/.zshrc  # 或 source ~/.bash_profile

3. 或者重启 Terminal

问题：不确定使用哪个 shell

症状： 不知道该编辑哪个配置文件。

解决方案： 查看当前使用的 shell：

echo $SHELL

• 如果输出 /bin/zsh，编辑 ~/.zshrc
• 如果输出 /bin/bash，编辑 ~/.bash_profile

系统权限问题

问题：macOS 阻止程序运行

症状： 首次运行时提示需要在系统偏好设置中允许。

解决方案：

1. 打开系统偏好设置 → 安全性与隐私
2. 在"通用"标签页中，允许相关程序运行
3. 重新运行命令

问题：需要 Xcode Command Line Tools

症状： 安装过程中提示需要安装 Xcode Command Line Tools。

解决方案： 安装 Command Line Tools：

xcode-select --install

网络问题

问题：防火墙阻止连接

症状： Claude Code 无法连接到服务器。

解决方案：

1. 检查系统防火墙设置
2. 在系统偏好设置 → 安全性与隐私 → 防火墙中，允许 Node 访问网络
3. 检查是否使用了代理或 VPN

仍然无法解决？

如果以上方法都无法解决你的问题，请：

1. 查看 通用常见问题
2. 联系技术支持
3. 提供详细的错误信息和系统版本