WSL Installation Guide - langningchen/miniapp GitHub Wiki

WSL 安装指南（Windows 用户必看）

本指南适用于 Windows 10/11 用户，帮助您安装 WSL2 (Windows Subsystem for Linux) 来运行 Ubuntu 系统。

📖 什么是 WSL？

WSL (Windows Subsystem for Linux) 是微软开发的兼容层，允许您在 Windows 系统上直接运行 Linux 环境，无需虚拟机或双系统。WSL2 是其最新版本，性能更佳。

🎯 为什么需要 WSL？

由于本项目需要在 Linux 环境下编译，Windows 用户有以下选择：

  • ✅ WSL2 - 推荐，性能好，集成度高
  • ❌ 虚拟机 - 性能较差，资源占用大
  • ❌ 双系统 - 切换麻烦，硬盘分区复杂

🔧 系统要求

  • Windows 10 版本 2004 及更高版本（内部版本 19041 及更高版本）
  • Windows 11 任意版本
  • 支持虚拟化的 CPU（大部分现代 CPU 都支持）

📋 安装步骤

步骤 1：检查 Windows 版本

  1. 按 Win + R 键，输入 winver，点击确定
  2. 查看版本号，确保满足系统要求

Windows 版本检查

步骤 2：启用 WSL 功能

方法一：使用 PowerShell（推荐）

  1. 右键点击开始菜单，选择"Windows PowerShell (管理员)"
  2. 在 PowerShell 中输入以下命令：
# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

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

方法二：使用图形界面

  1. 按 Win + R，输入 appwiz.cpl
  2. 点击左侧"启用或关闭 Windows 功能"
  3. 勾选以下两项：
    • ✅ 适用于 Linux 的 Windows 子系统
    • ✅ 虚拟机平台
  4. 点击确定，重启计算机

步骤 3：重启计算机

完成上述设置后，必须重启计算机才能继续。

步骤 4：设置 WSL2 为默认版本

重启后，再次以管理员身份运行 PowerShell：

wsl --set-default-version 2

步骤 5：安装 Ubuntu

方法一：从 Microsoft Store 安装（推荐）

  1. 打开 Microsoft Store
  2. 搜索 "Ubuntu"
  3. 选择 "Ubuntu 22.04 LTS" 或 "Ubuntu 20.04 LTS"
  4. 点击"安装"

方法二：使用命令行安装

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

步骤 6：初始化 Ubuntu

  1. 安装完成后，点击"启动"或在开始菜单找到 Ubuntu
  2. 首次启动会进行初始化，需要等待几分钟
  3. 系统会提示创建用户账号： 
    Enter new UNIX username: your_username
New password: [输入密码，不会显示]
Retype new password: [再次输入密码]

💡 提示: 密码输入时不会显示任何字符，这是正常现象！

✅ 验证安装

在 Ubuntu 终端中运行以下命令验证安装：

# 检查系统版本
lsb_release -a

# 检查 WSL 版本
cat /proc/version

您应该看到类似输出：

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.x LTS
Release:	22.04
Codename:	jammy

🔧 WSL 常用命令

在 Windows PowerShell 中：

# 查看已安装的 Linux 发行版
wsl --list --verbose

# 启动默认 Linux 发行版
wsl

# 关闭所有运行的 Linux 发行版
wsl --shutdown

# 重启 WSL
wsl --shutdown
wsl

🚀 下一步

安装完成后，请继续阅读：

❗ 常见问题

问题1：启用 WSL 功能时提示错误

解决方案：

  • 确保以管理员身份运行 PowerShell
  • 检查 Windows 版本是否满足要求
  • 在 BIOS 中启用虚拟化功能

问题2：wsl --install 命令不存在

解决方案：

  • 更新 Windows 到最新版本
  • 使用图形界面方法安装

问题3：Ubuntu 启动缓慢

解决方案：

  • 重启计算机
  • 运行 wsl --shutdown 后重新启动
  • 检查防火墙设置

问题4：忘记密码

解决方案：

# 重置用户密码
wsl -u root
passwd your_username
exit

需要帮助？ 查看 常见问题解决 或访问 Microsoft WSL 官方文档。