# wsl-tool

**Repository Path**: zyx3721/wsl-tool

## Basic Information

- **Project Name**: wsl-tool
- **Description**: wsl管理脚本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 1. 安装与初始配置

### 1.1 开启 WSL 功能

需要开启两个 Windows 可选功能，可通过 `wsl-toggle.ps1` 脚本一键操作（见第 4 章），或手动在"控制面板 → 启用或关闭 Windows 功能"中勾选：

- ✅ 适用于 Linux 的 Windows 子系统
- ✅ 虚拟机平台

开启后需**重启系统**。

> 参考：[Windows 系统开启 Hyper-V](https://blog.csdn.net/zhengaga/article/details/140054923) | [WSL2 安装教程](https://blog.csdn.net/x777777x/article/details/141092913)

### 1.2 安装发行版

方式一：命令行安装（推荐）

```powershell
# 查看可安装的发行版列表
wsl --list --online

# 安装 Ubuntu 22.04
wsl --install -d Ubuntu-22.04
```

也可通过 Microsoft Store 搜索 "Ubuntu 22.04" 直接安装。

方式二：从 .tar 备份导入（适用于迁移或恢复场景，可指定安装盘）：

```powershell
wsl --import <名称> <安装目录> <tar文件> --version 2
```

推荐使用 `wsl-toggle.ps1` 脚本操作（见第 4 章），支持自动推导名称和目录、进度监控、安全校验等。示例：

```
# 运行脚本 → 选择 [4] Import distro → 输入 tar 路径即可
powershell.exe -ExecutionPolicy Bypass -File "E:\01-HyperDir\wsl-toggle.ps1"

# 脚本会自动完成以下工作：
#   1. 校验 tar 文件（后缀、大小）
#   2. 从文件名推导发行版名称（如 guet-server-2026-03-01.tar → guet-server）
#   3. 自动生成独立安装目录（如 E:\01-HyperDir\WslData\guet-server\）
#   4. 显示汇总信息确认后执行，带实时进度监控
```

> 参考：[WSL2 迁移到其他盘](https://blog.csdn.net/a486259/article/details/136125740)

### 1.3 Ubuntu 22.04 换源（阿里云）

编辑 `/etc/apt/sources.list`：

```bash
deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse

# deb https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse
# deb-src https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
```

### 1.4 命令行提示符高亮

添加到 `~/.bashrc`：

```bash
export PS1='[\[\e[34;1m\]\u@\[\e[0m\]\[\e[32;1m\]\H\[\e[0m\]\[\e[31;1m\] \w\[\e[0m\]]$ '
```

### 1.5 配置默认启动用户

```powershell
wsl -d <发行版名称> --default-user <用户名>
```

> 参考：[设置 WSL 默认启动用户](https://blog.csdn.net/qq_37085158/article/details/131041223)



## 2. 开机自启与关闭

### 2.1 WSL 开机自启

创建 VBScript 脚本 `wsl-startup.vbs`：

```vbscript
set ws=wscript.CreateObject("wscript.shell")
ws.run "wsl --user wyl -d guet-server", 0
```

存放到 Windows 启动目录：

```
C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\wsl-startup.vbs
```

系统登录后会自动在后台启动指定发行版。

### 2.2 关闭 WSL

```powershell
# 关闭所有发行版
wsl --shutdown

# 仅终止指定发行版
wsl --terminate <发行版名称>
```

> 参考：[完全卸载 WSL 服务教程](https://blog.csdn.net/qq_73162098/article/details/145329101)

### 2.3 Docker Desktop 配置

WSL2 模式下 Docker Desktop 可直接使用 `localhost:port` 访问容器服务。

> 参考：[WSL2 Docker Desktop 配置](https://blog.csdn.net/qq_42977903/article/details/134815233)



## 3. 常用命令

### 3.1 基本操作

| 命令 | 说明 |
| ---- | ---- |
| `wsl` | 启动默认发行版 |
| `wsl -d <名称>` | 启动指定发行版 |
| `wsl --user <用户> -d <名称>` | 以指定用户启动 |
| `wsl --shutdown` | 关闭所有发行版 |
| `wsl --terminate <名称>` | 终止指定发行版 |

### 3.2 查询信息

| 命令 | 说明 |
| ---- | ---- |
| `wsl --list` | 列出所有已安装发行版 |
| `wsl --list --verbose` | 列出发行版详情（名称、状态、版本） |
| `wsl --list --running` | 列出正在运行的发行版 |

### 3.3 版本管理

| 命令 | 说明 |
| ---- | ---- |
| `wsl --set-version <名称> <1\|2>` | 转换指定发行版的 WSL 版本 |
| `wsl --set-default-version <1\|2>` | 设置新安装发行版的默认版本 |

### 3.4 导出 / 导入 / 删除

> 💡 迁移到其他盘的步骤：① 导出原系统 → ② 删除原发行版 → ③ 导入到新位置
>
> 以下操作推荐使用 `wsl-toggle.ps1` 脚本（第 4 章），带进度监控和安全保护。

**导出**：

```powershell
wsl --export <名称> <导出路径>

# 示例
wsl --export guet-server E:\01-HyperDir\guet-server-2026-03-01.tar
```

**导入**：

```powershell
wsl --import <名称> <安装目录> <tar文件> --version 2

# 示例（每个发行版应使用独立目录，避免 vhdx 覆盖）
wsl --import guet-server "E:\01-HyperDir\WslData\guet-server" "E:\01-HyperDir\guet-server-2026-03-01.tar" --version 2
```

**删除**：

```powershell
wsl --unregister <名称>

# 示例
wsl --unregister guet-server
```

> ⚠️ 删除操作不可逆，会清除发行版的全部数据。建议先导出备份。

### 3.5 使用脚本替代手动操作

上述导出/导入/删除命令需要手动拼写完整参数，容易出错。`wsl-toggle.ps1` 脚本（第 4 章）提供了交互式操作界面：

| 手动命令的痛点 | 脚本的改进 |
| ---- | ---- |
| 导入时需手动指定名称、目录、tar 路径、版本号 | 输入 tar 路径后自动推导名称和安装目录，回车即可 |
| 多个发行版导入同一目录会覆盖 vhdx 数据 | 每个发行版自动隔离到独立子目录 |
| 导出时不知道磁盘是否有足够空间 | 导出前自动检测磁盘剩余空间 |
| 误删正在运行的发行版导致数据丢失 | 自动检测运行状态，Running 时直接拦截 |
| 看不到导入/导出的进度，不知道还要多久 | 实时显示文件大小增长和已用时间 |
| 相对路径或带引号路径容易出问题 | 自动解析 `./`、`../`、拖放引号路径 |

快速启动：

```powershell
powershell.exe -ExecutionPolicy Bypass -File "E:\01-HyperDir\wsl-toggle.ps1"
```



## 4.WSL 功能管理工具（wsl-toggle.ps1）

> 一键管理 WSL 相关 Windows 功能的开启/关闭，以及发行版的导出、导入和删除操作，带进度监控和多重安全保护。

脚本路径：`E:\01-HyperDir\wsl-toggle.ps1`

### 4.1 运行方式

以管理员身份运行（脚本会自动检测并请求提权）：

```powershell
powershell.exe -ExecutionPolicy Bypass -File "E:\01-HyperDir\wsl-toggle.ps1"
```

如遇执行策略限制，先执行：

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

### 4.2 功能菜单

| 选项 | 功能 | 说明 |
| :--: | ---- | ---- |
| `1` | Enable WSL features | 开启"适用于 Linux 的 Windows 子系统"和"虚拟机平台" |
| `2` | Disable WSL features | 关闭上述两项功能 |
| `3` | Export distro | 导出发行版为 .tar 备份文件（带磁盘空间预检） |
| `4` | Import distro | 从 .tar 文件导入发行版（自动推导名称和安装目录） |
| `5` | Unregister distro | 删除发行版（拦截运行中的发行版 + 名称二次确认） |
| `6` | Refresh status | 刷新功能状态和发行版列表 |
| `0` | Exit | 退出工具 |

### 4.3 导出示例

运行脚本 → 选择 `3` → 选择发行版编号 → 回车使用默认路径或输入自定义路径

默认导出路径格式：`<脚本所在目录>\<发行版名称>-<yyyy-MM-dd>.tar`

例如：`E:\01-HyperDir\guet-server-2026-02-27.tar`

支持相对路径（如 `./backup.tar`）和拖放带引号路径，均自动解析为绝对路径。导出前会检测目标磁盘剩余空间，不足 1GB 时警告。

```
  Target drive E: free space: 48.72 GB

[ACTION] Exporting guet-server ...
  [/] 1.20 GB exported ... (elapsed: 0m 35s)
[OK] Export completed: E:\01-HyperDir\guet-server-2026-02-27.tar
     File size: 2.31 GB | Elapsed: 1m 08s
```

### 4.4 导入示例

运行脚本 → 选择 `4` → 交互流程如下：

| 步骤 | 操作 | 智能默认值 |
| :--: | ---- | ---- |
| 1 | 输入 .tar 文件路径 | 支持相对路径、拖放引号路径，自动校验后缀和文件大小 |
| 2 | 输入发行版名称 | 自动从文件名推导（去除日期后缀），如 `guet-server-2026-03-01.tar` → `guet-server` |
| 3 | 输入安装目录 | 自动基于 tar 所在目录生成：`<tar目录>\WslData\<发行版名>\` |
| 4 | 选择 WSL 版本 | 默认 WSL2 |
| 5 | 确认汇总信息 | 直接回车 = 确认执行 |

发行版名称仅允许字母、数字、连字符、下划线和点（`a-zA-Z0-9_-.`），含空格或特殊字符会被拦截。若自定义安装目录中已存在 `ext4.vhdx`，会提示追加子目录以防覆盖其他发行版数据。

```
  Enter .tar backup file path: ./guet-server-2026-03-01.tar
  Source file: E:\01-HyperDir\guet-server-2026-03-01.tar (4.52 GB)

  Default distro name: guet-server
  Press Enter to use default, or input custom name: ↵

  Default install directory: E:\01-HyperDir\WslData\guet-server
  Press Enter to use default, or input custom path: ↵

  Default WSL version: 2
  Press Enter to use default, or input 1: ↵

  ----------------------------------------
  Import Summary:
    Distro name : guet-server
    Source file : E:\01-HyperDir\guet-server-2026-03-01.tar (4.52 GB)
    Install dir : E:\01-HyperDir\WslData\guet-server
    WSL version : WSL2
  ----------------------------------------
  Proceed with import? (Y/N, default=Y): ↵

[ACTION] Importing guet-server (WSL2) ...
  [|] 1.05 GB written ... (elapsed: 0m 28s)
[OK] Import completed: guet-server (WSL2)
     Install dir: E:\01-HyperDir\WslData\guet-server | Elapsed: 0m 42s
```

### 4.5 删除示例

运行脚本 → 选择 `5` → 选择发行版编号 → 输入发行版名称进行二次确认

**安全保护**：如果选中的发行版正在运行（Running），会直接拦截并提示先停止：

```
[BLOCK] 'guet-server' is currently Running!
  To protect your data, running distros cannot be deleted directly.
  Please stop it first:  wsl --terminate guet-server
```

发行版为 Stopped 状态时才允许继续删除流程：

```
[WARN] This will permanently delete 'guet-server' and ALL its data!
  Type the distro name to confirm: guet-server
[OK] guet-server has been removed
```

### 4.6 注意事项

- 开启/关闭功能后需要**重启系统**才能生效，脚本会询问是否立即重启
- 导出/导入操作耗时取决于发行版大小，过程中会实时显示进度
- 删除操作不可逆，**正在运行的发行版会被拦截**，请确保已备份重要数据
- 所有路径输入支持相对路径（基于脚本所在目录解析）、绝对路径、拖放带引号路径
- 导入时每个发行版自动隔离到独立子目录，避免多个发行版共用目录导致数据覆盖
- 脚本使用 UTF-16LE 编码处理 `wsl.exe` 输出，在中文系统下不会出现乱码