Agent·Claude Code·Claude Code WSL2 AI 编程

WSL2 上安装 Claude Code 的完整指南

详细介绍在 WSL2 环境中安装和配置 Claude Code 的优势、步骤和最佳实践，为开发者提供更好的 AI 编程体验。

2026-05-01·1.3k 字·5 分钟

安装 Claude Code

Claude Code 官方推荐在 WSL2 环境中，直接运行以下安装脚本：

bash

curl -fsSL https://claude.ai/install.sh | bash

但在中国会遇到 App unavailable in region 问题，所以需要直接运行以下命令执行安装：

bash

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

输入 claude，看能否返回 Claude Code 版本号和启动画面。

claude-code-start

应该会出现以下错误：
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.
Note: Claude Code might not be available in your country. Check supported countries at https://anthropic.com/supported-countries
不过没关系，我们可以通过 cc-switch 绕过这个限制。

卸载 Claude Code

卸载只需要在 WSL2 中依次执行以下命令：

bash

# 删除 Claude Code 二进制文件和版本文件
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# 删除全局 npm 包
npm uninstall -g @anthropic-ai/claude-code

# 删除用户设置和状态
rm -rf ~/.claude
rm ~/.claude.json

# 删除特定于项目的设置（从您的项目目录运行）
rm -rf .claude
rm -f .mcp.json

安装 CC Switch

在 CC Switch Release 下载最新版本。

CC Switch 有 Linux 版本的，但体验不如 Windows 版，特别是通知、托盘图标、开机自启等，所以我们直接下载 Windows 版。

cc-switch-start

装完后，点击右侧加号添加模型 API。

可以多添加几个，便于切换，有些厂商会提供免费额度。

在 WSL2 等环境使用 Claude Code 或 Codex 的时候，可手动指定为 WSL 里的配置目录，供应商数据与主环境保持一致。

在设置 > 高级 > 配置文件目录 > 配置目录覆盖中，把 Windows 的路径改为 WSL2 的路径。

例如把 C:\Users\Bowie\.claude 更改为 \\wsl.localhost\Ubuntu\home\bowie\.claude

这时再启动 Claude Code，就可以正常使用了。

wsl2-claude-code

🛠️ 安装步骤详解

第一步：安装 WSL2

1.1 启用 WSL 功能

打开 PowerShell（管理员权限）并运行：

powershell

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

1.2 设置 WSL2 为默认版本

powershell

# 设置 WSL2 为默认版本
wsl --set-default-version 2

# 检查 WSL 版本
wsl -l -v

1.3 安装 Linux 发行版

推荐使用 Ubuntu：

powershell

# 安装 Ubuntu
wsl --install -d Ubuntu

# 或者从 Microsoft Store 安装

第二步：配置 Linux 环境

2.1 基本设置

bash

# 更新包管理器
sudo apt update && sudo apt upgrade -y

# 安装必要工具
sudo apt install -y curl wget git build-essential

2.2 安装 Node.js

推荐使用 NodeSource 仓库安装最新 LTS 版本：

bash

# 安装 Node.js LTS
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

2.3 安装 pnpm（推荐）

bash

# 安装 pnpm
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 或者使用 npm
npm install -g pnpm

# 验证安装
pnpm --version

第三步：安装 Claude Code

3.1 全局安装

bash

# 使用 npm 安装
npm install -g @anthropic-ai/claude-code

# 或者使用 pnpm
pnpm add -g @anthropic-ai/claude-code

3.2 验证安装

bash

# 检查版本
claude --version

# 查看帮助
claude --help

第四步：配置 VS Code 集成

4.1 安装必要扩展

在 Windows 端 VS Code 安装 "Remote - WSL" 扩展
在 WSL 中打开项目文件夹
安装 Claude Code VS Code 扩展

4.2 配置项目

bash

# 在 WSL 中打开项目
code /path/to/your/project

# 初始化 Claude Code
claude status

🔧 最佳实践

项目文件管理

推荐：项目放在 WSL 文件系统内

bash

# 创建项目目录
mkdir -p ~/projects
cd ~/projects

# 克隆或创建项目
git clone your-repo.git
# 或
mkdir my-project && cd my-project

避免：跨文件系统操作

❌ 避免频繁访问 /mnt/c/ 下的文件
✅ 将项目放在 WSL 文件系统内（/home/user/projects）
✅ 使用符号链接如果需要访问 Windows 文件

环境变量配置

在 `~/.bashrc` 或 `~/.zshrc` 中添加：

bash

# Node.js 相关
export NPM_TOKEN="your_token_here"

# Claude Code 配置
export CLAUDE_CODE_API_KEY="your_api_key_here"

# 代理设置（如果需要）
export HTTP_PROXY="http://localhost:7890"
export HTTPS_PROXY="http://localhost:7890"

性能优化

1. WSL 配置文件

创建或编辑 C:\Users\YourUser\.wslconfig：

ini

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

# 可选：指定虚拟机交换空间
swap=2GB

# 可选：禁用 GUI 应用支持
guiApplications=false

2. 文件系统优化

bash

# 在 WSL 中创建项目，而不是在 /mnt/c/ 下
cd ~/projects  # ✅ 推荐
cd /mnt/c/Users/YourUser/projects  # ❌ 避免

🔍 验证安装

基础功能测试

bash

# 1. 检查 WSL2 状态
wsl -l -v

# 2. 验证 Node.js
node --version
npm --version
pnpm --version

# 3. 验证 Claude Code
claude --version
claude status

# 4. 测试项目操作
cd ~/projects/your-project
claude status

常见问题排查

问题 1：WSL2 启动缓慢

解决方案：

检查 .wslconfig 配置
重启 WSL：wsl --shutdown
确保足够的内存分配

问题 2：网络连接问题

解决方案：

bash

# 检查网络
ping google.com

# 如果需要代理
export HTTP_PROXY="http://host-ip:port"
export HTTPS_PROXY="http://host-ip:port"

问题 3：权限问题

解决方案：

bash

# 修复 npm 权限
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER /usr/local/lib/node_modules

# 或者使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

🎯 为什么这是最佳选择？

🚀 下一步

安装完成后，你可以：

探索 Claude Code 功能
bash
```
claude --help
claude status
```
配置你的项目
bash
```
cd ~/projects/your-project
claude status
```
开始 AI 辅助编程
- 使用自然语言描述需求
- 让 Claude Code 帮你生成代码
- 优化现有代码质量

系列：Claude Code

1 / 1

1.WSL2 上安装 Claude Code 的完整指南

本文为作者原创文章，遵循 CC BY-NC-ND 4.0 协议。转载时请注明出处，禁止商用。

Agent·Claude Code·Claude Code WSL2 AI 编程

WSL2 上安装 Claude Code 的完整指南

详细介绍在 WSL2 环境中安装和配置 Claude Code 的优势、步骤和最佳实践，为开发者提供更好的 AI 编程体验。

2026-05-01·1.3k 字·5 分钟

安装 Claude Code

Claude Code 官方推荐在 WSL2 环境中，直接运行以下安装脚本：

bash

curl -fsSL https://claude.ai/install.sh | bash

但在中国会遇到 App unavailable in region 问题，所以需要直接运行以下命令执行安装：

bash

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

输入 claude，看能否返回 Claude Code 版本号和启动画面。

claude-code-start

应该会出现以下错误：
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.
Note: Claude Code might not be available in your country. Check supported countries at https://anthropic.com/supported-countries
不过没关系，我们可以通过 cc-switch 绕过这个限制。

卸载 Claude Code

卸载只需要在 WSL2 中依次执行以下命令：

bash

# 删除 Claude Code 二进制文件和版本文件
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# 删除全局 npm 包
npm uninstall -g @anthropic-ai/claude-code

# 删除用户设置和状态
rm -rf ~/.claude
rm ~/.claude.json

# 删除特定于项目的设置（从您的项目目录运行）
rm -rf .claude
rm -f .mcp.json

安装 CC Switch

在 CC Switch Release 下载最新版本。

CC Switch 有 Linux 版本的，但体验不如 Windows 版，特别是通知、托盘图标、开机自启等，所以我们直接下载 Windows 版。

cc-switch-start

装完后，点击右侧加号添加模型 API。

可以多添加几个，便于切换，有些厂商会提供免费额度。

在 WSL2 等环境使用 Claude Code 或 Codex 的时候，可手动指定为 WSL 里的配置目录，供应商数据与主环境保持一致。

在设置 > 高级 > 配置文件目录 > 配置目录覆盖中，把 Windows 的路径改为 WSL2 的路径。

例如把 C:\Users\Bowie\.claude 更改为 \\wsl.localhost\Ubuntu\home\bowie\.claude

这时再启动 Claude Code，就可以正常使用了。

wsl2-claude-code

🛠️ 安装步骤详解

第一步：安装 WSL2

1.1 启用 WSL 功能

打开 PowerShell（管理员权限）并运行：

powershell

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

1.2 设置 WSL2 为默认版本

powershell

# 设置 WSL2 为默认版本
wsl --set-default-version 2

# 检查 WSL 版本
wsl -l -v

1.3 安装 Linux 发行版

推荐使用 Ubuntu：

powershell

# 安装 Ubuntu
wsl --install -d Ubuntu

# 或者从 Microsoft Store 安装

第二步：配置 Linux 环境

2.1 基本设置

bash

# 更新包管理器
sudo apt update && sudo apt upgrade -y

# 安装必要工具
sudo apt install -y curl wget git build-essential

2.2 安装 Node.js

推荐使用 NodeSource 仓库安装最新 LTS 版本：

bash

# 安装 Node.js LTS
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

2.3 安装 pnpm（推荐）

bash

# 安装 pnpm
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 或者使用 npm
npm install -g pnpm

# 验证安装
pnpm --version

第三步：安装 Claude Code

3.1 全局安装

bash

# 使用 npm 安装
npm install -g @anthropic-ai/claude-code

# 或者使用 pnpm
pnpm add -g @anthropic-ai/claude-code

3.2 验证安装

bash

# 检查版本
claude --version

# 查看帮助
claude --help

第四步：配置 VS Code 集成

4.1 安装必要扩展

在 Windows 端 VS Code 安装 "Remote - WSL" 扩展
在 WSL 中打开项目文件夹
安装 Claude Code VS Code 扩展

4.2 配置项目

bash

# 在 WSL 中打开项目
code /path/to/your/project

# 初始化 Claude Code
claude status

🔧 最佳实践

项目文件管理

推荐：项目放在 WSL 文件系统内

bash

# 创建项目目录
mkdir -p ~/projects
cd ~/projects

# 克隆或创建项目
git clone your-repo.git
# 或
mkdir my-project && cd my-project

避免：跨文件系统操作

❌ 避免频繁访问 /mnt/c/ 下的文件
✅ 将项目放在 WSL 文件系统内（/home/user/projects）
✅ 使用符号链接如果需要访问 Windows 文件

环境变量配置

在 `~/.bashrc` 或 `~/.zshrc` 中添加：

bash

# Node.js 相关
export NPM_TOKEN="your_token_here"

# Claude Code 配置
export CLAUDE_CODE_API_KEY="your_api_key_here"

# 代理设置（如果需要）
export HTTP_PROXY="http://localhost:7890"
export HTTPS_PROXY="http://localhost:7890"

性能优化

1. WSL 配置文件

创建或编辑 C:\Users\YourUser\.wslconfig：

ini

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

# 可选：指定虚拟机交换空间
swap=2GB

# 可选：禁用 GUI 应用支持
guiApplications=false

2. 文件系统优化

bash

# 在 WSL 中创建项目，而不是在 /mnt/c/ 下
cd ~/projects  # ✅ 推荐
cd /mnt/c/Users/YourUser/projects  # ❌ 避免

🔍 验证安装

基础功能测试

bash

# 1. 检查 WSL2 状态
wsl -l -v

# 2. 验证 Node.js
node --version
npm --version
pnpm --version

# 3. 验证 Claude Code
claude --version
claude status

# 4. 测试项目操作
cd ~/projects/your-project
claude status

常见问题排查

问题 1：WSL2 启动缓慢

解决方案：

检查 .wslconfig 配置
重启 WSL：wsl --shutdown
确保足够的内存分配

问题 2：网络连接问题

解决方案：

bash

# 检查网络
ping google.com

# 如果需要代理
export HTTP_PROXY="http://host-ip:port"
export HTTPS_PROXY="http://host-ip:port"

问题 3：权限问题

解决方案：

bash

# 修复 npm 权限
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER /usr/local/lib/node_modules

# 或者使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

🎯 为什么这是最佳选择？

🚀 下一步

安装完成后，你可以：

探索 Claude Code 功能
bash
```
claude --help
claude status
```
配置你的项目
bash
```
cd ~/projects/your-project
claude status
```
开始 AI 辅助编程
- 使用自然语言描述需求
- 让 Claude Code 帮你生成代码
- 优化现有代码质量

系列：Claude Code

1 / 1

1.WSL2 上安装 Claude Code 的完整指南

本文为作者原创文章，遵循 CC BY-NC-ND 4.0 协议。转载时请注明出处，禁止商用。

安装 Claude Code

卸载 Claude Code

安装 CC Switch

🛠️ 安装步骤详解

第一步：安装 WSL2

1.1 启用 WSL 功能

1.2 设置 WSL2 为默认版本

1.3 安装 Linux 发行版

第二步：配置 Linux 环境

2.1 基本设置

2.2 安装 Node.js

2.3 安装 pnpm（推荐）

第三步：安装 Claude Code

3.1 全局安装

3.2 验证安装

第四步：配置 VS Code 集成

4.1 安装必要扩展

4.2 配置项目

🔧 最佳实践

项目文件管理

推荐：项目放在 WSL 文件系统内

避免：跨文件系统操作

环境变量配置

在 ~/.bashrc 或 ~/.zshrc 中添加：

性能优化

1. WSL 配置文件

2. 文件系统优化

🔍 验证安装

基础功能测试

常见问题排查

问题 1：WSL2 启动缓慢

问题 2：网络连接问题

问题 3：权限问题

🎯 为什么这是最佳选择？

🚀 下一步

系列：Claude Code

安装 Claude Code

卸载 Claude Code

安装 CC Switch

🛠️ 安装步骤详解

第一步：安装 WSL2

1.1 启用 WSL 功能

1.2 设置 WSL2 为默认版本

1.3 安装 Linux 发行版

第二步：配置 Linux 环境

2.1 基本设置

2.2 安装 Node.js

2.3 安装 pnpm（推荐）

第三步：安装 Claude Code

3.1 全局安装

3.2 验证安装

第四步：配置 VS Code 集成

4.1 安装必要扩展

4.2 配置项目

🔧 最佳实践

项目文件管理

推荐：项目放在 WSL 文件系统内

避免：跨文件系统操作

环境变量配置

在 ~/.bashrc 或 ~/.zshrc 中添加：

性能优化

1. WSL 配置文件

2. 文件系统优化

🔍 验证安装

基础功能测试

常见问题排查

问题 1：WSL2 启动缓慢

问题 2：网络连接问题

问题 3：权限问题

🎯 为什么这是最佳选择？

🚀 下一步

系列：Claude Code

在 `~/.bashrc` 或 `~/.zshrc` 中添加：

在 `~/.bashrc` 或 `~/.zshrc` 中添加：