[个人笔记] WSL 完整使用指南及 Claude Code 配置记录

📝 说明

本文档仅作为个人技术笔记记录，部分内容可能已过时。

特别是 Claude Code 相关的安装配置，新版本已支持直接在 Windows 上安装，无需通过 WSL 环境。本文记录的是早期版本需要 WSL 的安装方法，现已不再适用。

WSL 相关的配置和使用方法仍然有效，可作为 Windows 开发环境配置的参考。

1. 安装配置

1.1 自动安装 WSL（推荐）

以管理员身份运行 PowerShell：

powershell 复制代码

wsl --install

1.2 设置 WSL2 为默认版本

powershell 复制代码

wsl --set-default-version 2

1.3 安装 Linux 发行版

powershell 复制代码

# 查看可用的发行版
wsl --list --online
wsl -l -o

# 安装默认的 Ubuntu
wsl --install

# 安装指定发行版
wsl --install -d Ubuntu-24.04

2. 基本管理命令

2.1 查看已安装的发行版

powershell 复制代码

# 简单列表
wsl --list
wsl -l

# 详细信息（包括版本和状态）
wsl --list --verbose
wsl -l -v

2.2 启动和停止

powershell 复制代码

# 启动默认发行版
wsl

# 启动指定发行版
wsl -d Ubuntu

# 关闭所有 WSL 实例
wsl --shutdown

# 终止指定发行版
wsl --terminate Ubuntu

2.3 设置默认发行版

powershell 复制代码

wsl --set-default Ubuntu

3. 备份和迁移

3.1 导出发行版（备份）

powershell 复制代码

# 创建备份目录
mkdir D:\Program\WSL

# 导出 Ubuntu 为 tar 文件
wsl --export Ubuntu D:\Program\WSL\wsl-ubuntu24.04.tar

3.2 注销发行版

powershell 复制代码

# 注意：这会删除所有数据
wsl --unregister Ubuntu

3.3 导入发行版（恢复/迁移）

powershell 复制代码

# 从备份文件导入新的发行版
wsl --import Ubuntu D:\Program\WSL\wsl-ubuntu24.04 D:\Program\WSL\wsl-ubuntu24.04.tar

4. 目录迁移详细步骤

4.1 完整迁移流程

powershell 复制代码

# 1. 导出当前发行版
wsl --export Ubuntu G:\WSL\wsl-ubuntu24.04.tar

# 2. 注销当前发行版
wsl --unregister Ubuntu

# 3. 导入到目标目录
wsl --import Ubuntu G:\WSL\wsl-ubuntu20.04 G:\WSL\wsl-ubuntu24.04.tar

# 4. 验证迁移
wsl --list --verbose

5. WSL 内部环境配置

5.1 进入 WSL 终端

bash 复制代码

# 在 Windows Terminal 或 PowerShell 输入
wsl

5.2 系统更新

bash 复制代码

# 更新软件包列表
sudo apt update

# 升级已安装的软件包
sudo apt upgrade

5.3 查看系统信息

bash 复制代码

# 查看 Ubuntu 版本
lsb_release -a

# 查看内核版本
uname -r

# 查看系统资源
htop

6. 开发环境配置

6.1 Node.js 和 npm 安装

bash 复制代码

# 方法1：使用 apt 安装
sudo apt install nodejs npm

# 方法2：使用 NodeSource 官方源（推荐）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

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

6.2 Python 环境

bash 复制代码

# 安装 Python 3 和 pip
sudo apt install python3 python3-pip

# 验证安装
python3 --version
pip3 --version

6.3 Git 配置

bash 复制代码

# 安装 Git
sudo apt install git

# 配置用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

7. Claude Code 安装（历史记录 - 已过时）

⚠️ 重要提醒：Claude Code 新版本已支持直接在 Windows 上安装，无需通过 WSL 环境。以下内容仅作为历史记录保存，展示早期版本的复杂安装过程。

7.1 NPM 配置（早期版本需要）

bash 复制代码

# 配置 npm 全局安装目录（可选）
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 配置 npm 平台
npm config set os linux

7.2 安装 Claude Code（早期版本方法）

bash 复制代码

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

# 如遇权限问题
sudo npm install -g @anthropic-ai/claude-code

# 如遇平台识别问题
npm install -g @anthropic-ai/claude-code --force --no-os-check

7.3 启动 Claude Code（早期版本方法）

bash 复制代码

# 进入项目目录
cd /mnt/c/your/project/path

# 启动 Claude Code
claude

现在的安装方式：Claude Code 新版本支持直接在 Windows 上安装，无需上述复杂配置。请查看官方文档获取最新安装方法。

8. 文件系统和路径

8.1 Windows 文件系统访问

bash 复制代码

# 访问 C 盘
cd /mnt/c/

# 访问 D 盘
cd /mnt/d/

# 访问用户目录
cd /mnt/c/Users/YourUsername/

8.2 WSL 与 Windows 路径转换

bash 复制代码

# WSL 路径转 Windows 路径
wslpath -w /home/username/project
# 输出：\\wsl$\Ubuntu\home\username\project

# Windows 路径转 WSL 路径
wslpath -u "C:\Users\YourName\Documents"
# 输出：/mnt/c/Users/YourName/Documents

9. VS Code 集成

9.1 安装 Remote-WSL 扩展

在 VS Code 扩展市场搜索并安装 "Remote - WSL"

9.2 在 WSL 中使用 VS Code

bash 复制代码

# 在当前目录打开 VS Code
code .

# 打开特定文件
code filename.js

10. 性能优化

10.1 内存和 CPU 限制

创建或编辑 %USERPROFILE%\.wslconfig 文件：

ini 复制代码

[wsl2]
memory=4GB
processors=2
swap=2GB

10.2 网络配置

bash 复制代码

# 查看网络配置
ip addr show

# 测试网络连接
ping google.com

11. 常见问题解决

11.1 权限问题

bash 复制代码

# 修改文件权限
chmod +x filename

# 修改目录权限
chmod -R 755 directory/

11.2 服务管理

bash 复制代码

# 启动服务
sudo systemctl start service_name

# 停止服务
sudo systemctl stop service_name

# 查看服务状态
sudo systemctl status service_name

11.3 网络问题

bash 复制代码

# 重置网络
sudo systemctl restart systemd-networkd

# 清理 DNS 缓存
sudo systemctl restart systemd-resolved

12. 实用命令汇总

12.1 WSL 管理

powershell 复制代码

# 查看 WSL 状态
wsl --status

# 更新 WSL
wsl --update

# 查看版本
wsl --version

# 设置默认用户
ubuntu config --default-user username

12.2 系统监控

bash 复制代码

# 查看磁盘使用
df -h

# 查看内存使用
free -h

# 查看进程
ps aux

# 实时监控
top

12.3 包管理

bash 复制代码

# 搜索包
apt search package_name

# 安装包
sudo apt install package_name

# 卸载包
sudo apt remove package_name

# 清理缓存
sudo apt autoremove
sudo apt autoclean

13. 备份策略

13.1 定期备份

powershell 复制代码

# 创建定期备份脚本
$date = Get-Date -Format "yyyy-MM-dd"
wsl --export Ubuntu "D:\WSL\Backup\ubuntu-backup-$date.tar"

13.2 项目备份

bash 复制代码

# 备份重要配置
tar -czf ~/backup-$(date +%Y%m%d).tar.gz ~/.bashrc ~/.profile ~/.gitconfig

注意事项

数据安全：导出/导入操作会影响整个发行版，请提前备份重要数据
版本兼容：确保 WSL 版本与目标发行版兼容
性能考虑：WSL2 在某些 I/O 操作上可能比原生 Linux 慢
网络限制：WSL 的网络配置可能需要额外设置
更新频率：定期更新 WSL 和 Linux 发行版以获得最新功能和安全补丁

这份指南涵盖了 WSL 的基本使用、高级配置和常见问题解决方案，适合作为日常参考文档。