Claude Code 安装与配置完全指南：新手5分钟上手的正确姿势

Claude Code 安装与配置完全指南：新手5分钟上手的正确姿势

Claude Code 安装配置指南封面

一句话结论：Claude Code 是 2025 年最值得新手入手的 AI 编程工具，但 90% 的人第一步就装错了——Windows 用户根本不需要折腾 WSL，npm 全局安装才是正解。

写在前面：为什么选 Claude Code？

作为一个从 Cursor、GitHub Copilot、ChatGPT 一路用过来的开发者，我得说句实话：Claude Code 是目前对新手最友好的 AI 编程助手。

不是因为它功能最多，而是因为它足够简单、足够直接。

  • Cursor 很好，但功能太复杂，新手容易迷失在无数设置里
  • Copilot 很快，但只能补全代码，不能帮你理解项目、重构架构
  • ChatGPT 很聪明，但它是"聊天模式"——你说一句它回一句，没法直接操作你的代码库

Claude Code 不一样。它是能直接操作你仓库的 AI 同事：

  • 你说"帮我加个用户列表页面"，它会自己读代码、写代码、跑测试
  • 你说"这个 bug 怎么修"，它会定位问题、给出修复、验证结果
  • 你说"重构这个模块"，它会分析依赖、制定计划、执行改动

但问题是：很多新手在安装这一步就卡住了。要么被各种教程误导去装 WSL，要么 API Key 配置错了连不上，要么装完发现命令找不到。

这篇文章，就是要把这些坑一次性填平。

第一步：安装前的准备（2分钟）

1.1 确认你的系统

Claude Code 支持：

  • macOS（最简单，一行命令搞定）
  • Linux（包括 WSL）
  • Windows（直接装，不需要 WSL！）

⚠️ 重要误区：很多教程说 Windows 必须用 WSL。这是过时信息。Claude Code 现在已经原生支持 Windows，直接用 npm 安装即可。

1.2 安装 Node.js

Claude Code 是基于 Node.js 开发的 CLI 工具，需要 Node.js 18+（推荐 20.x LTS）。

Windows/macOS 用户：

  1. 访问 nodejs.org
  2. 下载 LTS 版本（绿色按钮）
  3. 双击安装，全部默认选项即可

验证安装：

node -v
npm -v

看到版本号（如 v20.11.0）就说明装好了。

1.3 安装 Git（强烈推荐）

Claude Code 会用 Git 来读取项目历史、生成 diff、创建分支。虽然不强求，但强烈建议安装：

第二步：安装 Claude Code（3分钟）

2.1 全局安装（推荐）

打开终端（Windows 用 PowerShell，macOS 用 Terminal），执行：

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

2.2 验证安装

claude --version

看到版本号（如 2.1.143 (Claude Code)）说明安装成功。

如果提示"claude 不是内部命令"：

这是 Windows 用户最常见的问题。原因是 npm 全局安装目录没有加入系统 PATH。

解决方法：

  1. 找到 npm 全局目录：
npm config get prefix
  1. 把该目录下的 node_modules\.bin 加入系统环境变量 PATH
  2. 重新打开终端，再试 claude --version

第三步：配置 API Key（关键步骤）

3.1 获取 API Key

Claude Code 需要 Anthropic 的 API Key 才能工作。有两种方式：

方式 A：官方 Anthropic 账号（需海外支付）

  1. 访问 console.anthropic.com
  2. 注册账号并绑定信用卡
  3. 创建 API Key（格式如 sk-ant-api03-...）

方式 B：国内中转服务（推荐新手）
如果你无法绑定海外信用卡，可以使用国内中转服务：

  1. 访问 https://platform.deepseek.com/ 或其他中转平台
  2. 注册账号，充值少量金额（10元足够试用）
  3. 创建 API Key

3.2 配置环境变量

Windows（PowerShell）：

# 如果是官方 API
setx ANTHROPIC_API_KEY "你的API Key"

# 如果是中转服务，还需要设置 API 地址
setx ANTHROPIC_API_URL "https://api.cphone.vip"
setx ANTHROPIC_API_KEY "你的API Key"

macOS/Linux：

# 编辑 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_API_KEY="你的API Key"
# 如果是中转服务
export ANTHROPIC_API_URL="https://api.cphone.vip"

# 使配置生效
source ~/.zshrc

⚠️ 重要：设置环境变量后，必须重新打开终端才能生效。

3.3 验证配置

# Windows
echo $env:ANTHROPIC_API_KEY

# macOS/Linux
echo $ANTHROPIC_API_KEY

能看到你的 API Key 说明配置成功。

第四步：第一次运行 Claude Code

4.1 进入项目目录

Claude Code 是"项目感知"的——它会读取你当前目录的代码来理解上下文。

# 进入你的项目目录
cd D:\projects\my-app  # Windows
cd ~/projects/my-app   # macOS/Linux

# 启动 Claude Code
claude

4.2 首次运行引导

第一次启动时，Claude Code 会：

  1. 检测 Git 仓库：询问是否允许读取 Git 历史
  2. 请求文件权限：询问是否允许读取/修改当前目录的文件
  3. 选择模型：推荐选 claude-sonnet-4-20250514（性价比最高）

全部选 yes 即可。

4.3 界面说明

进入后你会看到一个类似聊天的界面：

╭─────────────────────────────────────────╮
│  Claude Code v2.1.143                    │
│  Model: claude-sonnet-4.6        │
│  Project: /Users/name/projects/my-app   │
╰─────────────────────────────────────────╯

>

光标处直接输入指令即可。

第五步：核心配置——CLAUDE.md

5.1 什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的项目级配置文件。每次启动时，Claude 会自动读取这个文件来获取项目上下文。

你可以把它理解为给 AI 同事的"入职手册"：

  • 项目技术栈是什么？
  • 代码规范有哪些？
  • 目录结构是怎样的？
  • 常用命令有哪些？

5.2 创建 CLAUDE.md

在项目根目录创建 CLAUDE.md 文件：

# 项目概述

这是一个基于 React + TypeScript 的前端项目，使用 Vite 构建工具。

## 技术栈

- 前端框架: React 18
- 语言: TypeScript
- 构建工具: Vite
- 样式: Tailwind CSS
- 状态管理: Zustand
- 路由: React Router v6

## 代码规范

- 使用函数组件 + Hooks
- 类型定义放在 `src/types/` 目录
- 组件放在 `src/components/` 目录
- 页面组件放在 `src/pages/` 目录
- API 请求封装在 `src/api/` 目录

## 常用命令

```bash
npm run dev      # 启动开发服务器
npm run build    # 构建生产版本
npm run test     # 运行测试
npm run lint     # 代码检查

注意事项

  • 所有 API 请求必须通过 src/api/client.ts 封装
  • 表单验证使用 Zod
  • 错误处理统一使用 toast 提示

### 5.3 CLAUDE.md 的最佳实践

根据我的实际使用经验，CLAUDE.md 有**三个关键原则**：

**原则 1：不要写太长**

ETH Zurich 的研究表明，超过 60 行的 CLAUDE.md 反而会降低 Claude 的表现。控制在 30-50 行最佳。

**原则 2：聚焦"做什么"而非"怎么做"**

❌ 不好的写法：
```markdown
## 添加组件的步骤

1. 在 src/components 创建文件夹
2. 创建 index.tsx
3. 写 interface Props
4. 写组件函数
5. 导出组件

✅ 好的写法：

## 组件规范

- 新组件放在 `src/components/ComponentName/index.tsx`
- 必须定义 Props 接口
- 使用默认导出

原则 3：包含具体约束

Claude 需要明确的边界条件：

  • "使用单引号而非双引号"
  • "接口名必须以 I 开头"
  • "不要直接使用 fetch，必须用封装好的 apiClient"

第六步：第一次实战——让 Claude 理解你的项目

配置完成后，建议先做一个"项目理解"对话：

> 请先阅读 README、package.json 和项目结构，告诉我：
> 1. 这是什么类型的项目？
> 2. 主要技术栈是什么？
> 3. 目录结构是怎样的？
> 4. 我应该从哪个入口文件开始理解？

Claude 会自动：

  • 读取 README.md
  • 分析 package.json 的依赖
  • 扫描目录结构
  • 识别入口文件

这个过程通常只需要 10-20 秒，但能让你和 Claude 建立共同的上下文基础。

第七步：常见错误与解决方案

错误 1："claude 不是内部或外部命令"

原因：npm 全局安装目录不在 PATH 中

解决：

# 找到全局目录
npm config get prefix

# 将该目录下的 node_modules\.bin 加入系统 PATH
# 重新打开终端

错误 2："API Key 无效" 或连接超时

原因：

  • API Key 复制时多了空格
  • 使用了中转服务但没有设置 ANTHROPIC_API_URL
  • 网络问题

解决：

# Windows 检查
$env:ANTHROPIC_API_KEY
$env:ANTHROPIC_API_URL

# 如果为空，重新设置并重启终端
setx ANTHROPIC_API_KEY "你的Key"

错误 3：文件权限不足（Windows）

原因：Windows 对 C 盘某些目录有写保护

解决：

  • 用管理员权限运行 PowerShell
  • 或把项目移到用户目录（如 D:\projects）

错误 4：CLAUDE.md 没生效

原因：文件位置不对或文件名错误

解决：

  • 确认文件在项目根目录
  • 确认文件名是 CLAUDE.md（不是 claude.md 或 Claude.md）
  • 重启 Claude Code 会话

什么时候不该用 Claude Code？

虽然 Claude Code 很强大，但它不是万能的：

场景 推荐工具 原因
快速单行补全 GitHub Copilot 更快、更轻量
纯算法题练习 ChatGPT/Claude 网页版 不需要操作文件系统
大型代码库首次分析 手动阅读 Claude Code 的上下文有限
预算紧张的个人开发者 Cursor Claude Code Max 每月 $200 较贵

我的建议：

  • 如果你是新手，想快速体验 AI 编程 → 用 Claude Code（按量付费版）
  • 如果你是专业开发者，每天写代码 4 小时以上 → 值得订阅 Claude Code Max
  • 如果你预算有限 → 用 Cursor Pro（$20/月）或 GitHub Copilot（$10/月）

总结：5 分钟上手清单

  1. ✅ 安装 Node.js 20.x LTS
  2. ✅ npm install -g @anthropic-ai/claude-code
  3. ✅ 设置 ANTHROPIC_API_KEY 环境变量
  4. ✅ 在项目根目录创建 CLAUDE.md
  5. ✅ 运行 claude，开始你的第一次对话

下一步建议：

试着给 Claude 一个具体任务：

> 帮我给这个项目添加一个登录页面：
> - 路由 /login
> - 表单字段：邮箱、密码
> - 调用 POST /api/login
> - 登录成功跳转到首页
> - 错误时显示提示
> 
> 请先给出实现计划，我确认后再开始写代码。

这就是 Claude Code 的正确打开方式：你说目标，它执行。

FAQ

Q1: Claude Code 和 Cursor 有什么区别？

A: Cursor 是"IDE + AI"，Claude Code 是"AI 操作你的代码"。Cursor 需要你在编辑器里工作，Claude Code 直接在终端里帮你改文件、跑命令、管理 Git。两者可以互补：用 Claude Code 做架构级改动，用 Cursor 做日常编码。

Q2: 没有海外信用卡能用 Claude Code 吗？

A: 可以。使用国内中转服务（如 https://platform.deepseek.com/），设置 ANTHROPIC_API_URL 环境变量指向中转地址即可。

Q3: Windows 真的不需要 WSL 吗？

A: 真的不需要。Claude Code 现在已经原生支持 Windows，npm 全局安装即可。那些教你装 WSL 的教程是过时的。

Q4: CLAUDE.md 必须写吗？

A: 不是必须，但强烈建议。没有 CLAUDE.md，Claude 每次都要重新理解你的项目；有了它，Claude 一上来就知道项目背景，效率提升至少 50%。

Q5: Claude Code 会改坏我的代码吗？

A: 有可能。所以一定要用 Git。Claude 每次改动都会生成 diff，你可以先 review 再确认。如果发现改坏了，随时 git checkout 回滚。


此博客中的热门博文

4个超好用的AI配音工具，自媒体短视频必备！免费！

图片
做自媒体声音不好听怎么办？不会配音，普通话不标准，这都没关系！分享超好用的AI配音工具，让枯燥的文字转成生动有趣的语音。影视解说、游戏解说、 纪录片解说 、美食解说、体育解说、旅游解说、知识科普、娱乐综艺、情感文案、企业宣传等博主都在用的免费配音软件，声音接近真人。 4个超好用的AI配音工具，自媒体短视频必备！ 1、Microsoft Azure Azure是微软旗下的一款 文本转语音 工具，140 种语言和变体的 400 种神经网络语音，通过简单地调整语速、音调、发音和停顿等，可实现与人声的语调和情感匹配的流畅、发音逼真自然的AI语音生成器。 截至目前为止，中文配音员一共32个，女配音员：晓萱、晓辰、晓涵、晓墨、晓秋、晓辰、晓睿、晓双、晓颜、晓悠、晓梦、晓伊、晓甄；男配音员： 云杨、云希、云野 、云枫、云皓、云健、云夏、云泽。 最近新增方言版的 云希(男，西南，云贵川桂 )、 云翔 (男，吉鲁) 、 云登 (男，河南) 、晓北 (女，东北) 、 晓妮 (女，陕西)。 曉臻 (女，台湾普通话) 、曉雨 (女，台湾普通话)、 雲哲 ( 男 ，台湾普通话) 、 曉曼 (女，粤语)、 曉佳 (女，粤语)、 雲龍 (男 ，粤语 ) 。 在西瓜、抖音、快手等视频平台里，我们所听到最多的就是 云希 的声音。 Azure链接： https://azure.microsoft.com/zh-cn/services/cognitive-services/text-to-speech/#features  ( 官方改版无法使用 ) 使用心得： 无需注册登录即可免费使用，不会存储你的数据，也无法导出音频文件。可以使用录屏或录音软件，录制已生成的音频。 2、Clipchamp Clipchamp是微软旗下公司，一个快捷简便而且免费的在线视频编辑器。 所有人都能轻松在浏览器中编辑视频，让任何人都能讲述值得分享的故事。 免费版的可以无限无水印导出，高达1080p (HD) 的导出分辨率，免费的音频、图像和视频素材、滤镜、效果、模板等，可免费使用于YouTube、Facebook、Instagram、Pinterest等社交媒体平台。 使用心得： 网页版本 需注册登录方可使用(直接用微软账号)，免费使用文字转语音工具！可导出视频和音频文件。虽然是基于Azure，但没有说话风格和音调的调节...
阅读全文

如何将文案快速制作成视频，这个方法太高效了

图片
 在之前的《 不露脸不出镜也能月入过万，零投入人人可操作的自媒体视频赚钱项目 》文章中，我简单的介绍了视频自媒体赚钱方法，而文案在自媒体中的重要性不言而喻。 每天制作视频，我会先 写文案 ，再查找素材，然后把写好的文案进行配音，再将视频素材和配音导入到视频编辑软件中剪辑。 其实这个过程，每天真的要花费很多时间去做，如 写文案 ，快的时候一个小时能写好，但是慢的时候几个小时也写不出来一篇。 在配音时，如果是自己配音，虽然对录音设备要求不高，但是要有安静的录音场地，而且还要带有感情色彩的。以1500字为例，录好一个音频可能要花上至少1个小时甚至更多时间。 如果没有合适的录音场地，那只好找一些录音软件替代， 省时省力 。 剪辑视频虽然没有写文案那么头疼，但是我们经常要事先准备好素材，才能快速完成剪辑。如果都是临时查找、下载，这些都要花费不少时间。 接下来，我会分享自己常用的解说视频创作方法， 简单高效 。 1、用到一个网站：票圈视频。免费好用的（建议电脑端使用） 它有很多常用的模版类型和案例视频，方便创作者使用。 知识讲解，情感，生活，教育演示，古风&影视，游戏，人文历史，健康养生。 比如：知识讲解，就是我最常用的。 2、选择一个模板，然后点“立即使用模板”进行创作。我在这选用“动物世界模板”。 进入创作页面后，我们能看到界面很直观地列出全部功能，文本输入框、视频图片素材、配音、背景音乐等。 3、按照自己的需求分别填充内容。 分段式的创作，在段落输入文案，选择相应的视频或者图片画面，也可以自定义上传素材，选择自己喜欢的配音员，选择语气等。 文章转视频，就这么简单的操作。 合成好的视频就可以在创作主页【我的视频】中找到。 最后，如果你是文章创作者，想要将文案快速制作成视频，这是不错的免费工具网站。 有这方面需求的网友可以试试。 如果想要增加收入，还可以开通自己的 Blogger 博客，赚取谷歌广告佣金。
阅读全文

国内如何干净下载谷歌 Chrome 浏览器，包含Windows + Mac + Linux + Android 正版离线安装包下载

图片
最近谷歌翻译突然用不了了，很多同学以为谷歌再没有适合我们使用的产品了。而作为一个开发者，常用的浏览器就是Chrome，简洁、快速，插件丰富，也是很多上网者的首选。 其实直接访问谷歌中国官网下载安装就行了。 国内可以访问的谷歌中国官网（三个都一样）： https://www.google.cn/chrome/ https://www.google.cn/chrome/ index.html https://www.google.cn/intl/zh-CN/chrome/ index.html是网站首页的网页文件。 注意：在这里，你直接点击下载按钮，下载下来的“ChromeSetup.exe”是一个在线安装包，如下图，1.36MB。 它在安装时，必须网络环境保持畅通，对于有些无网络和网速慢的朋友们来说非常不方便。 Chrome 浏览器离线安装包下载 在原官方网址后加了个“?standalone=1”，standalone(独立)，即独立安装包。 https://www.google.cn/chrome/?standalone=1 https://www.google.cn/chrome/index.html?standalone=1 网页会根据你访问的设备进行识别，然后提供相应的版本。比如，你的电脑系统是Windows，直接给你下载“ChromeStandaloneSetup64.exe”文件，大小88.89MB，这就是一个离线安装包。 你也可以使用以下链接下载相应的版本： Windows ： https://www.google.cn/intl/zh-CN/chrome/?standalone=1&platform=win64 Mac： https://www.google.cn/intl/zh-CN/chrome/?standalone=1&platform=mac64 如果你想下载更多的或适用于其他电子设备的版本，比如Linux、Mac、Android。 访问以上网址，通过 Ctrl+f 输入“其他平台”或者下拉到最底部也可以找到。 在这里你会发现，想要下载Android版的Chrome，就会跳转到Google play，网页无法访问！！ Android版 目前国内很多手机应用商店都已经下架Android版的Chrome浏览器了。有些可以下载的网...
阅读全文