Claude Code 安装及使用教程

1- 📌 概述

Claude Code 是 Anthropic 推出的 终端集成式 AI 代码助手，通过 WSL 2（Windows Subsystem for Linux）在 Windows 10 上运行，支持代码分析、Git 操作、缺陷修复等功能。本教程以 Windows 10 用户为目标，覆盖从环境搭建到核心功能使用的全流程，助你高效编码！

2- 🛠️ 前置准备（Windows 10 必做）

2.1- 系统与环境要求

组件 要求说明 检查/操作方法
Windows 版本 Windows 10 2004 及以上（需启用 WSL 2） 按 Win + R 输入 winver，查看版本号
WSL 2 已安装并设置为默认版本 打开 PowerShell，执行 wsl -l -v（需显示 Ubuntu 22.04+）
硬件虚拟化 已开启（BIOS/UEFI 中启用 VT-x/AMD-V） 任务管理器 → 性能 → CPU → 虚拟化（显示 " 已启用 "）
Node.js 18.16.0+（WSL 环境） WSL 终端执行 node -v（需输出 v18.16.0 或更高）
git 2.35.0+（WSL 环境） WSL 终端执行 git --version（需输出 2.35.0 或更高）

2.2- 安装 WSL 2（Windows 10 核心步骤）

步骤 1：启用 WSL 功能

  1. 以管理员身份打开 PowerShell，复制粘贴以下命令并回车：

    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

  2. 重启电脑完成安装。

步骤 2：安装 WSL 2 内核更新包

步骤 3：设置 WSL 2 为默认版本
在 PowerShell 中执行：

wsl --set-default-version 2

步骤 4：安装 Linux 子系统（推荐 Ubuntu 22.04）

  1. 打开 Microsoft Store，搜索 “Ubuntu 22.04 LTS” 并点击 " 获取 " 安装。
  2. 启动 Ubuntu 终端（首次启动会提示设置用户名和密码，按提示完成）。

3- 🚀 安装步骤

3.1- 安装 Node.js/npm（WSL 环境）

Claude Code 依赖 Node.js 18.16.0+，在 Ubuntu 终端中选择以下任意一种方式安装：

方法 1：通过 NodeSource 安装（推荐，简单快捷）

# 添加 NodeSource 源（18.x 版本）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

# 安装 Node.js 和 npm
sudo apt-get install -y nodejs

# 验证安装（输出 v18.16.0 或更高）
node -v  # 示例：v18.16.0
npm -v   # 示例：9.5.1

方法 2：通过 nvm 安装（灵活管理版本，适合多版本切换）

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重启终端后，安装 Node.js 18.16.0
nvm install 18.16.0
nvm use 18.16.0  # 设置为默认版本

3.2- 全局安装 Claude Code

sudo npm install -g @anthropic-ai/claude-code  # WSL 中使用 sudo 避免权限问题

3.3- 启动并完成 OAuth 认证

claude  # 启动终端工具，首次运行自动跳转认证页面

首次启动需完成以下操作：

  1. 浏览器自动打开 Anthropic 登录页面（若未自动打开，手动访问 https://console.anthropic.com）。
  2. 登录/注册 Anthropic 开发者账号（推荐使用 Google 或 GitHub 快速登录）。
  3. 在控制台创建 “Claude Code” 应用（或使用默认权限），授予 " 代码分析 ""Git 操作 " 等必要权限。
  4. 浏览器提示 " 授权成功 " 后，终端显示 " 登录成功 "，完成认证。

4- 📚 核心功能使用

4.1- 交互模式与路径说明

Claude Code 在 WSL 终端中运行，项目目录支持两种路径格式：

  • WSL 原生路径：如 ~/projects/my-app（推荐，无需额外转换）。
  • Windows 本地路径：如 /mnt/c/Users/你的用户名/Desktop/my-app（直接访问 Windows 文件）。

示例：

# 进入 Windows 桌面的项目目录（WSL 路径）
cd /mnt/c/Users/张三/Desktop/my-app

4.2- 核心功能详解

4.2.1- 代码理解与分析

  • 功能：快速定位文件/函数、生成架构图、解释逻辑（支持中文路径）。

  • 示例：

    用户：解释 src/payment/cache.js 里的缓存策略  
Claude：检测到 Redis 缓存模块（行号 15-30），过期时间默认 30 分钟...（附代码片段高亮）

4.2.2- Git 操作自动化

  • 提交代码：

    用户：提交当前更改，备注“修复登录接口 401 错误”  
Claude：检测到 2 个文件修改（src/api/auth.ts、tests/login.test.ts），是否确认提交？(输入 confirm)  
# 确认后，Claude 自动生成提交信息并执行 git commit（WSL 中操作 Git 仓库）

  • PR 管理：
    输入 创建 PR 到主分支，标题“优化支付缓存性能”，Claude 自动生成变更描述并提交（需确保本地已关联 GitHub 仓库）。

4.2.3- 代码修复与重构

  • 功能：自动修复常见错误（类型错误、未处理 Promise 拒绝）。

  • 示例：

    用户：修复 auth 模块中未处理的 Promise 拒绝错误  
Claude：检测到 3 处未捕获的 async/await 错误，生成修复补丁（显示 diff）...是否应用？(输入 apply)  
# 确认后，Claude 自动执行 git apply 应用补丁（修改保存在 WSL 文件系统中）

4.2.4- 测试与调试

  • 运行测试：

    用户：运行 src/auth 模块的单元测试  
Claude：执行 npm test -- auth，显示 2 个失败用例（如“无效令牌应返回 401”），分析原因为 token 解析逻辑错误...

5- ⚙️ 高级配置

5.1- 配置文件位置

Claude Code 的配置文件存储在 WSL 用户目录下，路径为：

~/.claude/config.json  # 即 /home/你的WSL用户名/.claude/config.json

自定义配置示例（解决 Windows 路径问题）：

{
  "shortcuts": {
    "/test": "生成当前文件的单元测试模板",  // 自定义快捷指令
    "/ignore": "将目录加入 .claudeignore"    // 快速忽略大文件/目录（如 /mnt/c/Users/张三/Desktop/my-app/node_modules）
  },
  "theme": "auto"  // 自动适配终端颜色方案（推荐）
}

5.2- 权限与安全

  • 高危命令拦截：Claude Code 自动拒绝 rm -rf /、sudo 等危险操作（提示 " 操作被拦截 "）。
  • 输入清理：过滤恶意代码片段（如 SQL 注入 payload），避免 Windows 系统受损。

5.3- 性能优化

  • 排除大文件/目录：在项目根目录（WSL 路径）创建 .claudeignore，添加 node_modules/ dist/ logs/ 等（减少分析负载）。

    # 在 WSL 终端中创建 .claudeignore（若项目在 WSL 中）
touch ~/.claudeignore
# 或（若项目在 Windows 路径）
touch /mnt/c/Users/张三/Desktop/my-app/.claudeignore

  • 网络加速：国内用户可通过代理访问（配置环境变量，WSL 中生效）：

    # 临时设置代理（替换为你的代理地址）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

6- 🔒 安全与隐私

6.1- 数据处理机制

Claude Code 默认通过 加密通道 将代码片段发送至 Anthropic 服务器生成建议，Windows 本地不会存储代码分析记录（仅 WSL 临时缓存，重启后清除）。

6.2- 隐私保护

  • 若需完全本地处理（功能受限），可在 Anthropic 控制台开启 " 隐私模式 "（需验证企业账号）。
  • 避免在项目中存储敏感信息（如 API 密钥、数据库密码），Claude Code 可能识别并提示风险。

7- ❓ Windows 10 常见问题与解决方案

问题类型 错误提示 解决方案 适用场景
WSL 未安装 wsl: command not found 按 "2.1 系统要求 " 启用 WSL 2 并安装 Ubuntu 首次使用 WSL
Node.js 版本低 Error: Node.js version 14.x is not supported 按 “3.1 安装 Node.js” 升级至 18.16.0+ 安装后启动失败
认证失败 OAuth flow failed 检查 Windows 防火墙是否拦截浏览器；清除浏览器缓存重新登录 网络环境复杂（如公司内网）
路径错误 Cannot find module '/mnt/c/…' 确认项目路径为 WSL 可访问格式（如 /mnt/c/Users/…） 访问 Windows 本地文件失败
性能卡顿 响应延迟 >5 秒 排除无关目录（.claudeignore）；切换有线网络（避免 Wi-Fi 干扰） 大项目分析缓慢

8- 📚 附录：Windows 10 学习资源