WSL 2 上安装 Claude Code 的完整指南

为什么选择 WSL2 安装 Claude Code？

在现代开发环境中，选择合适的工具链配置至关重要。虽然 Claude Code 可以在 Windows 原生环境中运行，但 WSL2（Windows Subsystem for Linux 2） 提供了更优越的开发体验。

🚀 核心优势

1. 完整的 Linux 开发环境

原生支持 Unix 工具链（grep, sed, awk 等）
更好的 Shell 体验（bash/zsh）
与 Linux 服务器环境保持一致

2. 工具链兼容性

Node.js、npm/pnpm 在 Linux 环境下运行更稳定
Git 操作更流畅，避免 Windows 路径问题
包管理器（apt, yum）简化依赖安装

3. 路径处理一致性

统一使用正斜杠（/）路径分隔符
避免 Windows 驱动器字母（C:\）带来的复杂性
与大多数开源项目文档保持一致

4. 性能优化

WSL2 的虚拟化性能已大幅提升
文件系统访问优化
内存管理更高效

5. 社区支持

绝大多数开发工具文档基于 Unix 环境
社区解决方案更多
避免 Windows 特有的兼容性问题

🛠️ 安装步骤详解

第一步：安装 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

🎯 为什么这是最佳选择？

对于 Obsidian 插件开发

正如我们之前处理的 Obsidian R2 上传插件项目，WSL2 环境提供了：

更好的 TypeScript 支持
- 更快的编译速度
- 更稳定的工具链
简化的构建流程
- esbuild 等工具运行更稳定
- 避免 Windows 路径问题
一致的团队开发环境
- 与团队成员环境保持一致
- 减少 "在我机器上能运行" 问题

对于 AI 编程助手

Claude Code 作为 AI 编程工具，在 WSL2 环境中能够：

更好地理解项目结构
- 统一的路径格式
- 标准的 Unix 工具链
提供更准确的建议
- 基于 Linux 环境的最佳实践
- 避免 Windows 特有的问题
更流畅的集成体验
- 与 VS Code Remote 无缝集成
- 更好的终端支持

🚀 下一步

安装完成后，你可以：

探索 Claude Code 功能
bash
```
claude --help
claude status
```

配置你的项目

bash

cd ~/projects/your-project
claude status

开始 AI 辅助编程
- 使用自然语言描述需求
- 让 Claude Code 帮你生成代码
- 优化现有代码质量

选择 WSL2 环境安装 Claude Code，将为你的开发工作带来更流畅、更高效的体验。这不仅是工具的选择，更是开发环境的优化升级！

相关链接：

为什么选择 WSL2 安装 Claude Code？

🚀 核心优势

1. 完整的 Linux 开发环境

原生支持 Unix 工具链（grep, sed, awk 等）
更好的 Shell 体验（bash/zsh）
与 Linux 服务器环境保持一致

2. 工具链兼容性

Node.js、npm/pnpm 在 Linux 环境下运行更稳定
Git 操作更流畅，避免 Windows 路径问题
包管理器（apt, yum）简化依赖安装

3. 路径处理一致性

统一使用正斜杠（/）路径分隔符
避免 Windows 驱动器字母（C:\）带来的复杂性
与大多数开源项目文档保持一致

4. 性能优化

WSL2 的虚拟化性能已大幅提升
文件系统访问优化
内存管理更高效

5. 社区支持

绝大多数开发工具文档基于 Unix 环境
社区解决方案更多
避免 Windows 特有的兼容性问题

🛠️ 安装步骤详解

第一步：安装 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

🎯 为什么这是最佳选择？

对于 Obsidian 插件开发

正如我们之前处理的 Obsidian R2 上传插件项目，WSL2 环境提供了：

更好的 TypeScript 支持
- 更快的编译速度
- 更稳定的工具链
简化的构建流程
- esbuild 等工具运行更稳定
- 避免 Windows 路径问题
一致的团队开发环境
- 与团队成员环境保持一致
- 减少 "在我机器上能运行" 问题

对于 AI 编程助手

Claude Code 作为 AI 编程工具，在 WSL2 环境中能够：

更好地理解项目结构
- 统一的路径格式
- 标准的 Unix 工具链
提供更准确的建议
- 基于 Linux 环境的最佳实践
- 避免 Windows 特有的问题
更流畅的集成体验
- 与 VS Code Remote 无缝集成
- 更好的终端支持

🚀 下一步

安装完成后，你可以：

探索 Claude Code 功能
bash
```
claude --help
claude status
```

配置你的项目

bash

cd ~/projects/your-project
claude status

开始 AI 辅助编程
- 使用自然语言描述需求
- 让 Claude Code 帮你生成代码
- 优化现有代码质量

选择 WSL2 环境安装 Claude Code，将为你的开发工作带来更流畅、更高效的体验。这不仅是工具的选择，更是开发环境的优化升级！

相关链接：

为什么选择 WSL2 安装 Claude Code？

🚀 核心优势

1. 完整的 Linux 开发环境

2. 工具链兼容性

3. 路径处理一致性

4. 性能优化

5. 社区支持

🛠️ 安装步骤详解

第一步：安装 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：权限问题

🎯 为什么这是最佳选择？

对于 Obsidian 插件开发

对于 AI 编程助手

🚀 下一步

为什么选择 WSL2 安装 Claude Code？

🚀 核心优势

1. 完整的 Linux 开发环境

2. 工具链兼容性

3. 路径处理一致性

4. 性能优化

5. 社区支持

🛠️ 安装步骤详解

第一步：安装 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：权限问题

🎯 为什么这是最佳选择？

对于 Obsidian 插件开发

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

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