AI 编程系列之 5：Claude Code 入门——从安装到第一个完整项目

- 前言
- [1. 为什么必须先装环境](#1. 为什么必须先装环境)
- - [1.1 Node.js：AI 编程的"地基"](#1.1 Node.js：AI 编程的"地基")
  - [1.2 Git：你的"后悔药"](#1.2 Git：你的"后悔药")
- [2. Claude Code 安装与 API 配置](#2. Claude Code 安装与 API 配置)
- - [2.1 一行命令装好 Claude Code](#2.1 一行命令装好 Claude Code)
  - [2.2 配置 API：让 Claude Code 能"上网思考"](#2.2 配置 API：让 Claude Code 能"上网思考")
- [3. 5 个必会终端命令](#3. 5 个必会终端命令)
- - [3.1 pwd ------ 我在哪？](#3.1 pwd —— 我在哪？)
  - [3.2 ls / dir ------ 看看这里有什么](#3.2 ls / dir —— 看看这里有什么)
  - [3.3 cd ------ 走到某个位置](#3.3 cd —— 走到某个位置)
  - [3.4 mkdir ------ 创建新文件夹](#3.4 mkdir —— 创建新文件夹)
  - [3.5 cat ------ 看看文件里写了什么](#3.5 cat —— 看看文件里写了什么)
- [4. 第一个完整项目：3 步做出一个 Web 小工具](#4. 第一个完整项目：3 步做出一个 Web 小工具)
- - [4.1 第 1 步：创建项目目录](#4.1 第 1 步：创建项目目录)
  - [4.2 第 2 步：启动 Claude Code，告诉它要做什么](#4.2 第 2 步：启动 Claude Code，告诉它要做什么)
  - [4.3 第 3 步：本地跑起来](#4.3 第 3 步：本地跑起来)
- [5. 新手最常踩的 3 个坑](#5. 新手最常踩的 3 个坑)
- - [5.1 坑 1：API Key 报错（`Invalid API Key` 或 `401 Unauthorized`）](#5.1 坑 1：API Key 报错（Invalid API Key 或 401 Unauthorized）)
  - [5.2 坑 2：终端权限问题（`EACCES: permission denied`）](#5.2 坑 2：终端权限问题（EACCES: permission denied）)
  - [5.3 坑 3：网络问题（Connection refused / 超时）](#5.3 坑 3：网络问题（Connection refused / 超时）)
- 结语
- 参考资料

前言

身边很多朋友问我："Claude Code 到底怎么装？我连 Node.js 是什么都不知道。"这篇文章就是来彻底打消这个顾虑的。我会带你从零开始：装环境、配 API、敲命令、做出第一个能跑的小工具。全程不用"懂代码"，你只需要会打字、会装软件。

上一篇《国内访问 AI 编程工具完全指南》讲清了为什么国内用户必须用中转方案，本篇就顺着那条路走------把 Claude Code 真正装进你的电脑、连上国产模型、跑出第一个项目。

1. 为什么必须先装环境

Claude Code 不是装在浏览器里就能用的图形化工具，它是一个运行在你电脑终端里的程序 。这意味着你的电脑需要先有两样东西：Node.js （让 JavaScript 跑起来的环境）和 Git（版本控制工具）。

听起来很技术，但请把心态摆正：这一步和"装 QQ"差不多。下载、安装、点下一步，完事。

1.1 Node.js：AI 编程的"地基"

Node.js 是 Claude Code 官方安装命令的前置依赖，npm（Node.js 自带的包管理器）是我们装 Claude Code 的工具。你可以把它理解为 AI 编程项目的基础运行环境------前端项目、Vite 脚手架、几乎所有现代 Web 项目都离不开它。

Windows 安装步骤：

打开浏览器，访问 https://nodejs.org/
你会看到两个版本按钮，选择左边的 LTS（长期支持版）------这是最稳的版本
下载完成后双击安装包
安装过程中一路点 Next，保持默认选项（关键：保持默认勾选的 "Add to PATH"）
点 Install 完成

macOS 安装步骤：

bash 复制代码

# 推荐用 nvm 管理 Node.js 版本，方便将来切换
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装完成后重启终端，然后：
$ nvm install --lts

验证安装（两台系统都执行）：

bash 复制代码

# 检查 Node.js 版本
$ node -v
# 预期输出：v20.x.x 或 v22.x.x

# 检查 npm 版本
$ npm -v
# 预期输出：10.x.x 或更高

注意：安装完成后必须关闭并重新打开终端，否则新装的命令可能找不到------这是无数新手栽过的坑。

1.2 Git：你的"后悔药"

Git 是版本控制工具。打个比方：你在写一篇文章，每改一版都存一份"论文_v1.doc"、"论文_v2.doc"、"论文_最终最终版.doc"......Git 就是帮你优雅管理这些版本的工具。

在 AI 编程中 Git 尤其重要------AI 有时候会改错代码。有了 Git，你可以随时"时光倒流"回到正确版本，这是你的后悔药。

Windows 安装：访问 https://git-scm.com/download/win，下载 64-bit 安装包，双击后保持所有默认选项一直点 Next 即可。

**macOS 安装：**macOS 通常自带 Git。打开终端输入 git --version，如果有输出就不需要装。如果没有：

bash 复制代码

$ xcode-select --install
# 弹窗点"安装"

首次配置（两台系统都执行）：

bash 复制代码

# 告诉 Git 你是谁（这些信息会记录在每次代码提交中）
$ git config --global user.name "Your Name"
$ git config --global user.email "your.email@example.com"

这里的名字和邮箱不需要真实，但建议和你将来注册 GitHub 的邮箱保持一致。

避坑：养成一个铁律------让 AI 做大的修改之前，先 git add . && git commit -m "保存当前进度" 。即使 AI 改坏了，也能用 git checkout . 恢复。这是无数开发者血泪总结出来的经验。

2. Claude Code 安装与 API 配置

环境装好后，下一步就是装 Claude Code 本体，然后让它真正能"思考"。

2.1 一行命令装好 Claude Code

官方提供了多种安装方式，本教程使用 npm 方式（和后续前端项目环境一致）：

bash 复制代码

# 全局安装 Claude Code
$ npm install -g @anthropic-ai/claude-code

提示：国内用户如果 npm 默认源速度慢，可以临时切到国内镜像：
bash 复制代码
$ npm config set registry https://registry.npmmirror.com
$ npm install -g @anthropic-ai/claude-code

验证安装：

bash 复制代码

$ claude --version
# 预期输出：claude-code v1.x.x

如果能看到版本号，恭喜你，安装成功！

2.2 配置 API：让 Claude Code 能"上网思考"

Claude Code 本身只是一个空壳------它需要 API Key 才能调用底层的大模型来"思考"。这就像你买了一个新手机，必须装 SIM 卡才能打电话。

方案一：直连 Anthropic 官方（适合海外用户）

如果你能稳定访问 Anthropic 服务，这是最直接的方案：

bash 复制代码

# macOS / Linux
$ echo 'export ANTHROPIC_API_KEY="sk-ant-你的Key"' >> ~/.zshrc
$ source ~/.zshrc

powershell 复制代码

# Windows PowerShell（永久设置）
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-你的Key", "User")

注意：永久设置后必须重新打开终端才生效。

方案二：国内用户中转方案（推荐）

国内直连 Anthropic 会遇到网络、配额、支付三个问题。好消息是，智谱、DeepSeek、MiniMax、Kimi 等国产厂商都已经提供了Anthropic Messages API 兼容端点------你不用改 Claude Code 任何代码，只需要把"目的地"从 Anthropic 官方切到国产模型，体验基本一致。

详细的国产模型对比、国内 Coding Plan 选择、cc-switch 切模型工具等内容，已经在上一篇博客里完整讲过，这里不重复。最关键的一步 是在 ~/.claude/settings.json 里写好下面这种配置：

bash 复制代码

# 创建配置文件目录
$ mkdir -p ~/.claude

然后用任意编辑器（推荐 VS Code）打开 ~/.claude/settings.json，按你使用的大模型写入对应配置：

智谱 GLM（推荐 Coding 场景）

json 复制代码

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "你的智谱Key",
        "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
        "API_TIMEOUT_MS": "3000000",
        "ANTHROPIC_MODEL": "GLM-4.6"
    }
}

DeepSeek（性价比之王）

json 复制代码

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek Key",
        "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
        "API_TIMEOUT_MS": "3000000",
        "ANTHROPIC_MODEL": "deepseek-chat"
    }
}

MiniMax M3（百万上下文 + 前沿 Coding）

json 复制代码

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "你的MiniMax Key",
        "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
        "API_TIMEOUT_MS": "3000000",
        "ANTHROPIC_MODEL": "MiniMax-M3"
    }
}

阿里云百炼 Qwen（备选）

bash 复制代码

$ export ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
$ export ANTHROPIC_API_KEY=YOUR_DASHSCOPE_API_KEY
$ export ANTHROPIC_MODEL=qwen3-coder-plus

配置完成后，验证 Claude Code 是否能正常调用模型：

bash 复制代码

# 重新打开终端后启动 Claude Code
$ claude

# 在交互界面输入：
/status

如果看到当前加载的模型名（GLM-4.6 / deepseek-chat / MiniMax-M3 等），就说明配置成功------接下来你就可以用自然语言让 AI 帮你写代码了。

避坑：API_TIMEOUT_MS 一定要设到 3000000（50 分钟），否则 Claude Code 跑长任务时会因为默认超时而中断------这是国产模型比 Anthropic 官方慢一点带来的小代价。

3. 5 个必会终端命令

很多新手看到"终端"两个字就头大。其实你只需要掌握 5 个命令，就能在 AI 编程的世界里畅通无阻。

我把这 5 个命令比作"逛商场的 5 个动作"------你看地图、走进某家店、看看货架、买一个新袋子、把货架上的说明书拿出来看。

3.1 pwd ------ 我在哪？

bash 复制代码

$ pwd
# Windows 输出：C:\Users\你的用户名
# macOS 输出：/Users/你的用户名

这就像在商场里看一下脚下地图上"您在此处"的标记。

3.2 ls / dir ------ 看看这里有什么

bash 复制代码

# macOS / Linux
$ ls

# Windows PowerShell
$ dir

预期输出（Windows）：

复制代码

Desktop    Documents   Downloads   Pictures   Videos
桌面       文档       下载       图片      视频

就像打开一个文件夹看看里面有什么。

3.3 cd ------ 走到某个位置

bash 复制代码

# 进入"桌面"文件夹
$ cd Desktop

# 返回上一级目录
$ cd ..

# 直接回到用户主目录
$ cd ~

cd 是 "change directory" 的缩写，就是"换个地方"的意思。

3.4 mkdir ------ 创建新文件夹

bash 复制代码

# 创建一个名为 my-project 的文件夹
$ mkdir my-project

# 验证：查看是否创建成功
$ ls

3.5 cat ------ 看看文件里写了什么

bash 复制代码

# Windows
$ cat README.md

# macOS / Linux 也可以用 cat

这就像拆开一个包装袋，看看里面的说明书。

验证：依次执行以下命令，确认你能正常操作：
bash 复制代码
$ pwd
$ mkdir ai-coding-test
$ cd ai-coding-test
$ pwd
$ cd ..
如果每条命令都能正常执行且没有报错，恭喜你，终端入门完成！
提示：在 AI 编程中，你常用的命令其实就这 5 个的排列组合。其他命令（比如复制文件、删除文件夹）让 Claude Code 自己执行就行------这是它最擅长的事。

4. 第一个完整项目：3 步做出一个 Web 小工具

好，环境装好了，命令也学了。现在我们来做一个真正能跑的东西：一个随机密码生成器 Web 小工具。

这个例子的好处是：需求简单、视觉效果直观、3 步就能跑起来。

4.1 第 1 步：创建项目目录

bash 复制代码

# 创建一个工作目录
$ mkdir ~/ai-coding-projects/password-generator
$ cd ~/ai-coding-projects/password-generator

# 初始化 Git
$ git init

4.2 第 2 步：启动 Claude Code，告诉它要做什么

bash 复制代码

# 启动 Claude Code
$ claude

你会看到一个交互式界面，光标等待你输入。试试输入下面这段需求：

复制代码

我要做一个网页版"随机密码生成器"。

需求：
1. 页面有一个标题"密码生成器"
2. 用户可以输入想要生成的密码长度（默认 12 位）
3. 用户可以勾选"包含数字"、"包含大写字母"、"包含特殊符号"三个选项
4. 点击"生成密码"按钮后，显示一个随机密码
5. 有一个"复制"按钮，可以把密码复制到剪贴板
6. 界面简洁美观，背景用渐变色

技术栈用纯 HTML + CSS + JavaScript，一个 index.html 文件搞定。
生成完成后请告诉我怎么在浏览器里打开。

Claude Code 会自己读项目、自己创建文件、自己写代码。完成后会告诉你它做了哪些事。

4.3 第 3 步：本地跑起来

在 Claude Code 完成后，它通常会告诉你启动方法。对纯 HTML 项目，你只需要：

bash 复制代码

# macOS
$ open index.html

# Windows
$ start index.html

或者直接在文件管理器里双击 index.html 文件，它会用你的默认浏览器打开。

【配图位置 4：随机密码生成器运行效果截图------渐变背景 + 输入框 + 三个勾选项 + 生成/复制按钮】

注意：如果你想保存这次的工作进度：
bash 复制代码
$ git add .
$ git commit -m "第一个项目：随机密码生成器"

整个过程，从打开终端到看到能跑的网页，10 分钟内完全可以搞定。

5. 新手最常踩的 3 个坑

下面这 3 个坑，我几乎每个月都要帮朋友解决一次。提前知道，能省你 2 小时排查时间。

5.1 坑 1：API Key 报错（`Invalid API Key` 或 `401 Unauthorized`）

症状：Claude Code 启动后输入任何指令都报错。

原因：API Key 复制错了、过期了、或者和它对应的服务没对上。

解决步骤：

检查 Key 是否复制完整------sk-ant- 前缀有没有被吞掉
检查 Key 的来源：智谱的 Key 不能用在 Anthropic 官方，反之亦然
重新打开终端（环境变量没刷新）
如果用的是 ~/.claude/settings.json 配置，确认 JSON 格式没写错（多余的逗号、缺引号都会导致整个文件失效）

5.2 坑 2：终端权限问题（`EACCES: permission denied`）

症状：在 macOS 上 npm install -g 报错，Windows 上 claude 命令找不到。

解决步骤：

macOS：修复 npm 全局目录权限，或者改用官方原生安装器
Windows ：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy RemoteSigned，然后重新安装

5.3 坑 3：网络问题（Connection refused / 超时）

症状：能启动 Claude Code，但每次发指令都超时或连接失败。

解决步骤：

如果你直连 Anthropic 官方------国内网络下基本必踩这个坑，请改用 DeepSeek/GLM/MiniMax 的兼容端点
如果你已经用了国产模型------检查 ANTHROPIC_BASE_URL 是否配对（智谱是 https://open.bigmodel.cn/api/anthropic，不是 /v1/chat/completions）
检查中转服务余额是否用完

避坑：3 个坑里最常见的是坑 1 ------Key 复制漏字符。养成习惯：复制完后手动核对前 4 位和后 4 位字符。

结语

到这里，你应该已经把 Claude Code 装好了、跑起来了、做出了第一个能用的 Web 小工具。整个过程用到的命令不超过 10 条，核心思路就一句话：打开终端 → 启动 cc → 用自然语言描述需求 → 看结果。

记住，AI 编程最反直觉的一点是：你越懂"怎么跟 AI 说话"，就越不需要懂代码。装好工具后，接下来要练的不是编程，是表达。

参考资料

Claude Code 官方文档：https://docs.claude.com/claude-code
Node.js 下载：https://nodejs.org/
智谱 Anthropic 兼容端点文档：https://docs.bigmodel.cn/cn/guide/develop/claude
DeepSeek Anthropic 兼容接口：https://api-docs.deepseek.com/guides/anthropic_api
MiniMax M3 模型介绍：https://api.minimaxi.com/

AI 编程系列之 5：Claude Code 入门——从安装到第一个完整项目

目录

前言

1. 为什么必须先装环境

1.1 Node.js：AI 编程的"地基"

1.2 Git：你的"后悔药"

2. Claude Code 安装与 API 配置

2.1 一行命令装好 Claude Code

2.2 配置 API：让 Claude Code 能"上网思考"

3. 5 个必会终端命令

3.1 pwd ------ 我在哪？

3.2 ls / dir ------ 看看这里有什么

3.3 cd ------ 走到某个位置

3.4 mkdir ------ 创建新文件夹

3.5 cat ------ 看看文件里写了什么

4. 第一个完整项目：3 步做出一个 Web 小工具

4.1 第 1 步：创建项目目录

4.2 第 2 步：启动 Claude Code，告诉它要做什么

4.3 第 3 步：本地跑起来

5. 新手最常踩的 3 个坑

5.1 坑 1：API Key 报错（Invalid API Key 或 401 Unauthorized）

5.2 坑 2：终端权限问题（EACCES: permission denied）

5.3 坑 3：网络问题（Connection refused / 超时）

结语

参考资料

5.1 坑 1：API Key 报错（`Invalid API Key` 或 `401 Unauthorized`）

5.2 坑 2：终端权限问题（`EACCES: permission denied`）