手残党必备：Claude Code安装避坑指南

作者： /

先交代背景：为什么写这个

x 10px rgba(0,0,0,.08);”

loading=”lazy” width=”800″ height=”500″>

刚拿到Claude Code的时候，我心想：这玩意儿应该跟装个pip包差不多吧？结果连踩三个坑，差点把电脑锤了。一个朋友直接卡在“安装界面”半小时不动——这谁受得了？

这篇教程适合：

<

ul>

  • 第一次装Claude Code的萌新
  • 装了一半卡住的倒霉蛋
  • 想省时间直接上手的效率党

    • 省流：10分钟搞定，不磨叽。

    *开篇图：一个敲键盘的猫，配上“我装个工具，结果装了3遍”的梗图*

    第一步：确认环境——别上来就装

    很多人第一步就翻车：直接扔命令行跑安装。结果报错“Python 3.8+ required”或者“ModuleNotFoundError”。

    先检查你电脑有没有这些：

    “bash

    检查Python版本（Claude Code要求3.8以上）

    python3 --version

    输出示例：Python 3.11.4

    检查是否装了git（不是必须但建议）

    git --version

    输出示例：git version 2.42.0

    `

    如果哪个版本低了或没装，直接去官网下最新版。别用apt或brew装，容易装到旧版本——我亲测用brew install python装了3.7，结果Claude Code报错，气得我手动重装。

    为什么要写这个？ 因为报错信息全是英文，新手看到“ModuleNotFoundError”直接懵了。其实很简单：缺啥补啥。

    第二步：安装Claude Code——两种姿势

    姿势1：pip安装（推荐）

    `bash

    用pip安装（建议用虚拟环境）

    pip install claude-code

    验证安装

    claude --version

    输出示例：0.2.0

    `

    这里有个坑：国内pip源有时候把包拦了。我第一次装，卡在“Installing dependencies”半小时，进度条不动。

    解决办法：换清华镜像

    `bash
    pip install claude-code -i https://pypi.tuna.tsinghua.edu.cn/simple
    `

    换完再跑，2分钟搞定。

    姿势2：通过Claude桌面版使用（适合不想装命令行的人）

    如果你不想折腾命令行环境，可以直接用Claude桌面版（官网下载），在设置里开启“Developer Mode”就能用类似功能。好处：开箱即用。坏处：不能直接在项目目录里跑命令。

    *中间图：终端截图，左边是失败报错（红色），右边是成功安装（绿色），形成视觉对比*

    第三步：配置——别跳过这一步

    装完直接claude init？错！很多人卡在这里。正确的姿势：

    1. 配置API密钥（必须）

    `bash

    设置环境变量（建议加到.zshrc或.bashrc）

    export ANTHROPIC_API_KEY="你的密钥"

    永久生效（以zsh为例）

    echo "export ANTHROPIC_API_KEY='你的密钥'" >> ~/.zshrc
    source ~/.zshrc

    验证

    echo $ANTHROPIC_API_KEY

    输出：sk-ant-xxxxx（部分隐藏）

    `

    另一个坑： 密钥不能有空格，不能有引号冲突。我见过有人把密钥写在双引号里又加了个单引号，结果跑不了。代码里写清楚就行。

    2. 初始化项目

    `bash

    进项目目录

    cd ~/my-project

    初始化（会生成.claude目录）

    claude init

    看生成了什么

    ls -la .claude/

    输出：config.json sessions/

    `

    这里有个反人类设计：init必须在项目根目录跑，不然报错。官方文档写的是“just run it”，但没说清楚在哪跑。

    第四步：验证——装好了没

    跑个最简单的测试：

    `bash

    创建一个测试文件

    echo "print('Hello Claude')" > test.py

    让Claude审查代码

    claude review test.py
    `

    如果输出类似：
    `
    Reviewing test.py...
    No issues found. The file is a simple Python script that prints a string.
    `

    那就装好了。如果报错“API key not found”或者“Connection refused”，回第三步重配。

    *总结前图：一个流程图，展示从安装到验证的完整路径，标注常见错误节点*

    踩坑记录：你可能遇到的3个问题

    坑1：权限不足

    报错：Error: Permission denied

    解决： 用虚拟环境避免冲突
    `bash
    python3 -m venv claude-env
    source claude-env/bin/activate
    pip install claude-code
    `

    坑2：网络超时

    报错：ETIMEDOUT 或 Connection refused

    解决： 换镜像源（见第二步），或开代理。

    坑3：Python版本不兼容

    报错：Unsupported Python version

    解决： 用pyenv管理Python版本。
    `bash

    用pyenv安装指定版本

    pyenv install 3.11
    pyenv global 3.11
    `

    总结一下，你可以立刻用的三个点

  • 装前检查两件套：Python 3.8+、Git（选装），缺啥补啥
  • 换源是王道：pip装不动就用清华镜像，2分钟搞定
  • 密钥别写错：环境变量配好，跑echo`验证，省得后面报API错误

    • 装好了下一步就是“写第一个Claude Code项目”，下篇聊。

    更多官方信息请参考：https://docs.anthropic.com/claude-code

    滚动至顶部