共计 2370 个字符，预计需要花费 6 分钟才能阅读完成。
作为一名长期在 Mac 上折腾开发环境的程序员，最近在配置 Claude Code 时踩了不少坑。特别是 M1 芯片的 ARM 架构兼容性问题，加上 Python 版本冲突，简直让人头大。经过一番摸索，终于整理出一套稳定的配置方案，分享给同样遇到问题的开发者们。
安装前的痛点分析
在 Mac 上安装 Claude Code 主要会遇到以下几个典型问题：
- ARM 架构兼容性问题：M1/M2 芯片的 Mac 使用的是 ARM 架构，很多 Python 包需要额外编译或者寻找特定版本
- Python 版本冲突：系统自带的 Python 版本通常较老，而 Claude Code 可能需要较新的 Python 3.8+ 版本
- 依赖项版本锁定：transformers、torch 等核心库版本不匹配会导致各种奇怪的报错
- 权限问题 ：Mac 的系统完整性保护(SIP) 有时会干扰某些目录的写入
基础环境配置
1. Homebrew 配置
Homebrew 是 Mac 上必不可少的包管理工具，我们先配置好它：
# 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 设置国内镜像源（加速下载）export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"2. Pyenv 虚拟环境管理
为了避免 Python 版本冲突，我们使用 pyenv 来管理多版本 Python：
# 安装 pyenv
brew install pyenv
# 安装 Python 3.8.12（Claude Code 推荐版本）pyenv install 3.8.12
# 创建项目专用虚拟环境
pyenv virtualenv 3.8.12 claude-code-env
# 激活虚拟环境
pyenv activate claude-code-env关键依赖安装
1. 准备 requirements.txt
创建一个包含关键依赖的 requirements.txt 文件：
# requirements.txt
# 核心依赖
torch==1.9.0 # 注意：M1 芯片需要使用 torch>=1.12.0 的 nightly 版本
transformers==4.18.0
# 辅助工具
tqdm==4.64.0
numpy==1.21.6
# 开发工具
black==22.3.0
flake8==4.0.12. 安装依赖
# 安装基础依赖
pip install -r requirements.txt
# M1 芯片用户需要单独安装 torch
arch -arm64 pip install --pre torch -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html环境验证
创建一个简单的验证脚本 check_env.py：
import torch
import transformers
print("PyTorch 版本:", torch.__version__)
print("Transformers 版本:", transformers.__version__)
print("CUDA 是否可用:", torch.cuda.is_available())
print("MPS 是否可用:", torch.backends.mps.is_available()) # M1 芯片专属运行验证：
python check_env.py避坑指南
M1 芯片特有问题解决方案
- torch 安装问题：
- 使用 nightly 版本：
pip install --pre torch -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html -
启用 Metal 加速：在代码中添加
device = torch.device('mps') -
内存不足问题：
- 减小 batch size
- 使用
del及时释放不再使用的变量 - 监控内存使用：
htop或activity_monitor
常见错误解决
- ModuleNotFoundError：通常是虚拟环境未激活或依赖未安装
- 版本冲突：严格按照 requirements.txt 中的版本安装
- 权限问题：避免使用 sudo，改用虚拟环境
性能调优
- 内存监控：
# 实时监控 Python 进程内存
while true; do ps -p $(pgrep -f python) -o %mem=,vsz=; sleep 1; done- GPU/MPE 加速：
# 在代码中优先使用硬件加速
device = torch.device('mps' if torch.backends.mps.is_available() else 'cpu')分享与思考
配置完成后，建议将你的安装脚本分享到 GitHub Gist，方便日后复用和他人参考。
最后留一个思考题：在大模型本地化部署越来越普遍的今天，你认为开发者在环境配置方面还面临哪些挑战？如何构建更友好的本地开发体验？欢迎在评论区分享你的见解。
希望这篇指南能帮助你顺利搭建 Claude Code 开发环境。如果遇到其他问题，欢迎交流讨论！
正文完
