[个人笔记] WSL 完整使用指南及 Claude Code 配置记录
📝 说明
本文档仅作为个人技术笔记记录，部分内容可能已过时。
特别是 Claude Code 相关的安装配置，新版本已支持直接在 Windows 上安装，无需通过 WSL 环境。本文记录的是早期版本需要 WSL 的安装方法，现已不再适用。
WSL 相关的配置和使用方法仍然有效，可作为 Windows 开发环境配置的参考。
1. 安装配置
1.1 自动安装 WSL（推荐）
以管理员身份运行 PowerShell：
wsl --install
1.2 设置 WSL2 为默认版本
wsl --set-default-version 2
1.3 安装 Linux 发行版
# 查看可用的发行版
wsl --list --online
wsl -l -o
# 安装默认的 Ubuntu
wsl --install
# 安装指定发行版
wsl --install -d Ubuntu-24.04
2. 基本管理命令
2.1 查看已安装的发行版
# 简单列表
wsl --list
wsl -l
# 详细信息（包括版本和状态）
wsl --list --verbose
wsl -l -v
2.2 启动和停止
# 启动默认发行版
wsl
# 启动指定发行版
wsl -d Ubuntu
# 关闭所有 WSL 实例
wsl --shutdown
# 终止指定发行版
wsl --terminate Ubuntu
2.3 设置默认发行版
wsl --set-default Ubuntu
3. 备份和迁移
3.1 导出发行版（备份）
# 创建备份目录
mkdir D:\Program\WSL
# 导出 Ubuntu 为 tar 文件
wsl --export Ubuntu D:\Program\WSL\wsl-ubuntu24.04.tar
3.2 注销发行版
# 注意：这会删除所有数据
wsl --unregister Ubuntu
3.3 导入发行版（恢复/迁移）
# 从备份文件导入新的发行版
wsl --import Ubuntu D:\Program\WSL\wsl-ubuntu24.04 D:\Program\WSL\wsl-ubuntu24.04.tar
4. 目录迁移详细步骤
4.1 完整迁移流程
# 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 终端
# 在 Windows Terminal 或 PowerShell 输入
wsl
5.2 系统更新
# 更新软件包列表
sudo apt update
# 升级已安装的软件包
sudo apt upgrade
5.3 查看系统信息
# 查看 Ubuntu 版本
lsb_release -a
# 查看内核版本
uname -r
# 查看系统资源
htop
6. 开发环境配置
6.1 Node.js 和 npm 安装
# 方法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 环境
# 安装 Python 3 和 pip
sudo apt install python3 python3-pip
# 验证安装
python3 --version
pip3 --version
6.3 Git 配置
# 安装 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 配置（早期版本需要）
# 配置 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（早期版本方法）
# 全局安装
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（早期版本方法）
# 进入项目目录
cd /mnt/c/your/project/path
# 启动 Claude Code
claude
现在的安装方式：Claude Code 新版本支持直接在 Windows 上安装，无需上述复杂配置。请查看官方文档获取最新安装方法。
8. 文件系统和路径
8.1 Windows 文件系统访问
# 访问 C 盘
cd /mnt/c/
# 访问 D 盘
cd /mnt/d/
# 访问用户目录
cd /mnt/c/Users/YourUsername/
8.2 WSL 与 Windows 路径转换
# 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
# 在当前目录打开 VS Code
code .
# 打开特定文件
code filename.js
10. 性能优化
10.1 内存和 CPU 限制
创建或编辑 %USERPROFILE%\.wslconfig 文件：
[wsl2]
memory=4GB
processors=2
swap=2GB
10.2 网络配置
# 查看网络配置
ip addr show
# 测试网络连接
ping google.com
11. 常见问题解决
11.1 权限问题
# 修改文件权限
chmod +x filename
# 修改目录权限
chmod -R 755 directory/
11.2 服务管理
# 启动服务
sudo systemctl start service_name
# 停止服务
sudo systemctl stop service_name
# 查看服务状态
sudo systemctl status service_name
11.3 网络问题
# 重置网络
sudo systemctl restart systemd-networkd
# 清理 DNS 缓存
sudo systemctl restart systemd-resolved
12. 实用命令汇总
12.1 WSL 管理
# 查看 WSL 状态
wsl --status
# 更新 WSL
wsl --update
# 查看版本
wsl --version
# 设置默认用户
ubuntu config --default-user username
12.2 系统监控
# 查看磁盘使用
df -h
# 查看内存使用
free -h
# 查看进程
ps aux
# 实时监控
top
12.3 包管理
# 搜索包
apt search package_name
# 安装包
sudo apt install package_name
# 卸载包
sudo apt remove package_name
# 清理缓存
sudo apt autoremove
sudo apt autoclean
13. 备份策略
13.1 定期备份
# 创建定期备份脚本
$date = Get-Date -Format "yyyy-MM-dd"
wsl --export Ubuntu "D:\WSL\Backup\ubuntu-backup-$date.tar"
13.2 项目备份
# 备份重要配置
tar -czf ~/backup-$(date +%Y%m%d).tar.gz ~/.bashrc ~/.profile ~/.gitconfig
注意事项
- 数据安全：导出/导入操作会影响整个发行版，请提前备份重要数据
- 版本兼容：确保 WSL 版本与目标发行版兼容
- 性能考虑：WSL2 在某些 I/O 操作上可能比原生 Linux 慢
- 网络限制：WSL 的网络配置可能需要额外设置
- 更新频率：定期更新 WSL 和 Linux 发行版以获得最新功能和安全补丁
这份指南涵盖了 WSL 的基本使用、高级配置和常见问题解决方案，适合作为日常参考文档。