开头我在这台 Windows 机器上折腾 WSL Ubuntu 和 Redis 安装前前后后花了整整一个下午。先说结论大部分Windows 无法安装 WSL Ubuntu的报错都不是系统真的不支持而是 Windows 功能没开全、版本跨度太大、或者残留了旧版 WSL 组件。真正把这几层问题理清之后从装好 Ubuntu 到跑起 Redis 并能在 Windows 侧连上其实只要二十分钟。这篇文章就围绕我实际踩过的坑来写。内容覆盖 WSL 1/2 的选型判断、WSL 安装失败的排错链路、Ubuntu 子系统的离线安装方案、在 WSL 里用 apt 装 Redis 并调整配置以及 VS Code 配合 WSL 做日常开发时要注意的细节。适合刚接触 WSL 的 Windows 开发者也适合在 Windows 上想用 Linux 原生 Redis 但一直被安装报错劝退的朋友。1. 装 WSL 之前必须想清楚的三件事1.1 系统版本和 WSL 1/2 选型——先用一条命令确定目标很多人上来就执行wsl --install结果提示成功却又无法启动 Ubuntu或者干脆卡住不动。我遇到的第一类问题就是不知道自己该装 WSL 1 还是 WSL 2。WSL 1 是把 Linux 系统调用翻译成 Windows 系统调用没有真正的 Linux 内核占用小、磁盘文件可以直接放在 Windows 文件系统里但和 Linux 内核行为有差异很多依赖底层行为的软件会跑出奇奇怪怪的问题。WSL 2 则是在 Hyper-V 虚拟机技术之上跑一个轻量级 Linux 内核兼容性好了太多Redis 这类对系统调用敏感的服务在 WSL 2 里跑和在真机 Linux 上跑基本没有区别。所以只要不是机器实在太老直接选 WSL 2 就对了。怎么判断当前机器能不能装 WSL 2打开管理员权限的 PowerShell执行systeminfo看输出里的 Hyper-V 要求那一项。如果四项都是是那虚拟化支持没有问题。只看这块还不够还要看 Windows 版本Windows 10 版本 2004Build 19041及以上建议用wsl --install自动安装Windows 10 版本 1903/1909需要手动启用 Windows 功能并单独安装内核更新包Windows 11 则任何版本都可以直接走新命令。我建议安装前先跑一下wsl --status如果提示 WSL 版本为 1那 Windows 功能可能没启用完整别急着装发行版。1.2 虚拟化开关BIOS 里的 SVM/Intel VT-x 检查WSL 2 依赖 CPU 虚拟化默认情况下很多品牌机在 BIOS 里是关着的。任务管理器切换到性能标签页右下角会看到虚拟化状态。如果显示已禁用那窗口系统里再怎么折腾都没用必须重启进 BIOS/UEFI 打开。Intel 平台的开关叫 Intel Virtualization TechnologyVT-xAMD 平台叫 SVM Mode部分主板还会叫 AMD-V。进 BIOS 的方式各品牌不同常见是开机时按 F2、F10、Del 中的一个。进去后在 Advanced / CPU Configuration / Virtualization 这类菜单里把对应项改成 Enabled保存重启。这里有个容易误判的情况任务管理器里虚拟化显示已启用但wsl --install装完 Ubuntu 启动时仍然报 Please enable the Virtual Machine Platform 或者 WSL2 requires an update。这种情况往往不是 BIOS 的问题而是 Windows 的可选功能没有真正启用需要在启用或关闭 Windows 功能里把虚拟机平台和适用于 Linux 的 Windows 子系统两项都勾上。如果你的电脑本身就是一台虚拟机比如在 VMware 或 VirtualBox 里跑 Windows那还要在虚拟机设置里开启虚拟化 Intel VT-x/AMD-V的嵌套虚拟化选项否则 WSL 2 无法启动。这一点很容易被忽略我就是在 VMware 里踩过一遍。1.3 分清这三个入口Windows 功能、商店包、wsl 命令无法安装 WSL这件事之所以让人头大是因为它涉及三层Windows 可选功能、商店里的 WSL 应用/发行版、以及wsl.exe命令行工具。很多人混着装了旧版又装新版最后一把乱。我建议先完全清干净再重新来一遍顺序不能反打开启用或关闭 Windows 功能勾选适用于 Linux 的 Windows 子系统和虚拟机平台重启系统打开 Microsoft Store搜索Windows Subsystem for Linux安装新版的 WSL 应用在管理员 PowerShell 里运行wsl --update保证内核组件是最新的最后再执行wsl --install -d Ubuntu安装发行版。很多网上教程直接让你执行wsl --install但这条命令在 Windows 10 老版本上只会启用功能不会自动装发行版甚至不提示你后续该干嘛。所以我更推荐手动拆开装每一层都确认成功再进行下一步出了问题也能定位到具体环节。2. 无法安装这个结论是怎么一步步排查出来的2.1 Your version of WSL is too old 的完整处理链路这个报错我在好几台机器上见过提示长这样Your version of Windows Subsystem for Linux is too old. Please update to the latest version by running: wsl --update很多人直接执行wsl --update然后发现要么没反应要么提示已经是最新但问题依旧。原因在于WSL 内核组件和应用商店的 WSL 包是分离的wsl --update只解决了命令行版本商店里的 WSL 应用如果没装到位内核依旧是老版本。完整处理链路# 1. 查看当前 WSL 内核是否正常 wsl --status # 2. 从商店更新 WSL 本身 # 打开 Microsoft Store搜索Windows Subsystem for Linux点击更新 # 3. 更新内核组件 wsl --shutdown wsl --update # 4. 设置默认版本为 WSL 2 wsl --set-default-version 2第 4 步经常会报一个额外的错WSL 2 需要更新其内核组件。这就要手动下载微软官方提供的 WSL 2 Linux 内核更新包wsl_update_x64.msi装完再执行一次wsl --set-default-version 2。如果不下载这个包直接换任何发行版都装不上。2.2 wsl --install 一直卡住可能是下载源太慢wsl --install会自动从微软服务器拉取发行版但这个过程在国内网络环境下经常非常慢甚至卡住不动。搜索热词里wsl --install 太慢占了很大比例说明这不是个例。我实测下来卡住的位置基本有两种一种是在下载 Ubuntu 发行版时长时间没有进度变化另一种是显示 Downloading the distribution 后直接跳到失败根本没有错误信息。这时别一直等直接关掉窗口改用离线方式安装。离线方案的思路是先从官网渠道下载 Ubuntu WSL 安装包或根文件系统压缩文件再通过wsl --import导入。这里不展开具体链接只说操作思路避免下载源不可控# 将下载好的 tar.gz 根文件系统导入为 WSL 发行版 wsl --import Ubuntu-Daily E:\WSL\Ubuntu-Daily ubuntu-wsl2.tar.gz --version 2导入之后用wsl -d Ubuntu-Daily进入再设置默认用户。这种方式不依赖商店下载速度稳定很多而且对后续做环境迁移、分发团队统一环境都很方便。2.3 卸载重装仍然失败一般是残留导致还有一种情况是以前装过旧版 Ubuntu 或其它发行版卸载不彻底导致新发行版装不上。常见表现是wsl --install -d Ubuntu显示安装成功但启动时直接报 WslRegisterDistribution failed。这时需要彻底清理。不要只在应用和功能里卸载还要手动删掉发行版在系统里的注册信息# 查看所有已安装发行版 wsl --list --verbose # 反注册并卸载指定发行版 wsl --unregister Ubuntu--unregister会把这个发行版的所有数据删掉包括文件系统和配置。执行完再检查%LOCALAPPDATA%\Packages下是否还有残留的发行版文件夹有就手动删除。之后重新打开一个管理员 PowerShell再走一遍安装流程。还有一个小细节Windows 商店里的 Ubuntu 如果一直显示已安装但装完无法启动可以在商店里先搜索到该应用点卸载然后重新安装。这两种卸载方式清理的位置不同叠加处理才干净。3. 从零到能用的 Ubuntu 子系统安装全程3.1 标准安装流程和首次启动注意事项如果前置检查都通过了安装 Ubuntu 最省事的方式还是用命令。以常见的 Ubuntu 22.04 为例# 管理员 PowerShell wsl --install -d Ubuntu-22.04装完之后系统会让设置 Linux 用户名和密码。这里有一个比较重要的建议用户名尽量和 Windows 用户名区分开不要用包含空格或非 ASCII 字符的名字否则后续 SSH、工具链配置时会有奇怪问题。密码只在 sudo 时用到但要记牢忘了就得在 Windows 侧执行ubuntu config --default-user root重置。进入系统后第一件事是更新软件源和系统软件sudo apt update sudo apt upgrade -y如果觉得 apt 下载速度慢可以把软件源换成国内镜像。操作方法是编辑/etc/apt/sources.list在文件开头添加镜像源地址然后注释掉原有地址。Ubuntu 22.04 和 24.04 的源格式不太一样修改前先备份原文件sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo nano /etc/apt/sources.list换完源再sudo apt update速度会明显改善。3.2 手动安装 Windows 离线包/根文件系统的备选路径我个人的推荐是直接把标准安装流程和离线方式都掌握因为后面换机器或帮同事排查时离线方式几乎百试百灵。离线方式有两种。一种是下载 Windows 商店应用的离线安装包后缀为 .appx双击安装即可另一种是下载 WSL 根文件系统压缩包用wsl --import导入。这两种方式里我更推荐第二种因为它不受商店限制而且可以自己指定发行版安装位置对系统盘空间紧张的人特别友好。导入命令wsl --import Ubuntu E:\WSL\Ubuntu ubuntu-22.04-wsl2.tar.gz --version 2注意wsl --import导入的发行版默认使用 root 用户登录需要通过/etc/wsl.conf指定默认用户[user] default你的用户名设置完成之后要重启 WSL 才生效在 Windows 侧执行wsl --shutdown再重新进入。3.3 让 WSL 里的 Ubuntu 用起来顺手换源、装常用包、注意文件换行装好系统后有些细节不处理的话后面写代码和跑 Redis 时会很别扭。我建议按这个顺序来# 安装常用工具 sudo apt install -y build-essential curl wget git vim net-tools # 配置 Git如果要用 git config --global user.name 你的名字 git config --global user.email 你的邮箱另外一个值得注意的点是在 WSL 里编辑 Windows 侧的代码文件时默认的 CRLF 换行符会导致 Linux 工具出现各种诡异问题比如#!/usr/bin/env bash报错、shell 脚本执行失败。如果是从 Windows 侧拷贝脚本进去先跑一句sed -i s/\r$// 脚本名把它转成 LF 格式。在 VS Code 里也可以直接点击右下角的行尾序列切换。3.4 Windows 与 Ubuntu 文件互访理解 /mnt/c 和 \wsl$WSL 和 Windows 是可以互相访问文件的这个特性很实用但机制要搞清楚否则容易把大量文件放在错误的位置拖慢系统。在 Ubuntu 里Windows 的 C 盘挂在/mnt/cD 盘挂在/mnt/d可以直接用命令行操作cd /mnt/c/Users/你的Windows用户名/Desktop不过要记住跨文件系统读写比纯 Linux 内部操作慢不少。比如用/mnt/c下的目录跑npm install或者 Redis 编译经常会慢到怀疑人生。正确的用法是把代码和依赖放在 WSL 自己的文件系统比如/home/用户名/需要和 Windows 交换文件时才通过/mnt/c拷贝。反过来在 Windows 里访问 WSL 文件系统可以在资源管理器地址栏输入\\wsl$\Ubuntu这样就能像访问网络共享一样看到 Ubuntu 的完整目录结构。VS Code 的 WSL 插件也是基于这套机制工作的它会自动把 Windows 侧的 VS Code 和 WSL 内部环境打通。4. Redis 装进 WSL安装、配置和 Windows 互通4.1 为什么在 WSL 里跑 Redis而不是用 Windows 原生版很多人图省事直接下载 Windows 版 Redis但官方早在多年前就不再维护 Windows 原生版了。网上流传的各种 Windows 编译版大多是社区个人维护版本滞后还经常缺少redis.conf完整配置、redis-cli部分命令不兼容等小毛病。在 WSL 里跑 Ubuntu 原生的redis-server版本和 Linux 生产环境一致配置经验可以直接迁移调试结果也更可靠。对比一下三种方案方案优点缺点Windows 社区编译版安装简单版本旧、无官方支持、配置不完整Docker Desktop 跑 Redis环境隔离、启动快吃内存、Docker 本身配置麻烦WSL 2 Ubuntu 原生 Redis接近生产环境、资源占用低、官方版本需要处理子系统网络和服务自启除非你已经在用 Docker 管理一堆服务否则我建议选择 WSL 2 原生安装。它对系统资源的占用比 Docker Desktop 小得多而且排查起来也直观。4.2 安装 Redis 并启动验证在 Ubuntu 里安装 Redis 非常简单sudo apt update sudo apt install -y redis-server装完后先看版本确认安装成功redis-server --version再测试能否正常启动sudo service redis-server start redis-cli ping如果返回PONG说明服务已经正常跑起来了。注意这里我用的是service redis-server start而不是直接用redis-server命令因为前者会把服务放到后台并且遵循 systemd 脚本里的配置后者会占据当前终端。如果service redis-server start提示无法连接到 systemd可以先检查一下 WSL 是否启用了 systemd。在 WSL 较新版本中可以通过/etc/wsl.conf启用[boot] systemdtrue修改后执行wsl --shutdown再重新进入然后systemctl status redis-server查看服务状态。4.3 核心配置项bind、protected-mode、requirepass 和持久化默认配置下 Redis 只允许本机访问这在一个 WSL 里本地开发够用了但如果要从 Windows 侧或者局域网内其他机器连进来就要动redis.conf。先找到配置文件位置sudo find /etc/redis -name redis.conf配置文件里最重要的几个选项# 监听地址0.0.0.0 表示允许所有网卡访问 bind 0.0.0.0 # 保护模式开启后没有密码的请求会被拒绝 protected-mode yes # 设置访问密码 requirepass 你的密码 # RDB 持久化默认开启 save 900 1 save 300 10 save 60 10000 # AOF 持久化默认关闭需要手动开启 appendonly yes appendfsync everysec我的实际建议是本机开发时把requirepass设上防止 WSL 的 IP 暴露在局域网中被别人扫描到protected-mode保持yesappendonly视场景开如果 Redis 里存的数据丢了无所谓就不用开开了会多一点磁盘写入和启动时间开销。修改配置后重启服务sudo service redis-server restart用密码连接测试redis-cli -a 你的密码 ping4.4 从 Windows 侧连接 WSL 里的 RedisWSL 2 使用 NAT 网络虚拟机有自己的 IP。从 Windows 侧访问 WSL 2 里的 Redis 有两种方式。第一种是直接访问 localhost。新版本 WSL 2 默认支持 localhost 转发所以你在 Windows 的命令行里直接redis-cli -h 127.0.0.1 -p 6379 -a 你的密码 ping大概率能通。但如果发现 localhost 连不上说明 localhost 转发没生效这时可以用第二种方式先拿到 WSL 的 IP。hostname -I # 比如输出 172.30.80.151然后在 Windows 里连172.30.80.151:6379。不过要注意WSL 2 在每次重启后 IP 可能会变所以依赖固定 IP 的场景更适合用 localhost 转发。还有一种更省心的方案在 Windows 侧装一个 Redis Desktop Manager 之类的可视化工具连接地址填127.0.0.1、端口6379、密码填上requirepass设置的值然后测试连接。如果连接成功就能以图形化界面查看 key、执行命令比纯命令行直观太多。4.5 局域网内访问 WSL Redis 的注意事项如果想让局域网内其他电脑也连到这个 Redis需要处理 portproxy 端口转发。因为 WSL 2 的 IP 是动态的所以每次 WSL 重启后都要重新执行 netsh 命令比较麻烦。netsh interface portproxy add v4tov4 listenaddress0.0.0.0 listenport6379 connectaddress172.30.80.151 connectport6379同时还需要在 Windows 防火墙中放行 6379 端口。我不太建议在开发机上一开始就开暴露到局域网因为 Redis 默认密码为空时极易被扫描入侵。如果只是给自己另一台电脑临时访问直接连 WSL 的 IP 就够了。5. 把这套环境当日常开发工具用的收尾细节5.1 在 VS Code 中使用 WSL 的完整体验VS Code 装上 WSL 插件后可以在 Windows 侧直接操作 WSL 里的代码。操作方式是在 VS Code 里按F1输入 WSL: Connect to WSL它会新开一个窗口并自动进入 WSL 文件系统。有一种常见场景是代码在 WSL 里工具链也在 WSL 里但 VS Code 窗口的界面仍然跑在 Windows 上两边无缝协作。这个模式下的好处很多终端默认就是 WSL 里的 bash不用手动切换Git 可以直接调用 WSL 里的 Git调试器能直接 attach 到 WSL 里跑的进程扩展安装时可以在WSL: Ubuntu这个分类里单独安装不影响 Windows 侧环境。需要注意安装扩展时如果不小心装到了 Windows 侧WSL 远端会提示无法扩展重新在 WSL 分类下安装一遍即可。5.2 WSL 内存/CPU 占用过高用 .wslconfig 限制WSL 2 默认会吃一半的物理内存这在 16G 或 8G 内存的机器上非常难受。Windows 侧在你的用户目录下创建一个.wslconfig文件可以限制资源[wsl2] memory4GB processors2 swap2GB localhostForwardingtrue创建完成后在 PowerShell 执行wsl --shutdown再重新进入 WSL 使配置生效。执行free -h可以看到内存已经变成 4G。这里我特别强调一下localhostForwardingtrue要保留否则 Windows 访问 WSL 里的 Redis localhost 转发会失效。5.3 WSL 虚拟磁盘膨胀、空间不足的回收方法用久了 WSL 的 ext4.vhdx 文件会越来越大即使删除了大量文件磁盘空间也不会自动归还给 Windows。我遇到过一次 vhdx 膨胀到几十个 G但 WSL 里实际只用了几个 G 的情况。回收空间的操作# 1. 关闭 WSL wsl --shutdown # 2. 管理员 CMD 进入 diskpart diskpart # 选择虚拟磁盘文件 select vdisk fileC:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_*\LocalState\ext4.vhdx # 挂载为只读 attach vdisk readonly # 压缩 compact vdisk # 卸载 detach vdisk # 退出 exit执行完后Windows 资源管理器里就能看到 vhdx 文件大小明显减小。这个方法对 WSL 2 所有发行版通用找到对应的 vhdx 文件路径就行。5.4 每次进 WSL 都要手动起 Redis配置自启动WSL 不会在开机时就启动 Linux 服务所以每次进入 Ubuntu 后 Redis 可能没在运行。除了手动执行sudo service redis-server start还有两种方式可以改善。在启用了 systemd 的 WSL 较新版本中直接把 Redis 设成开机自启sudo systemctl enable redis-server如果 WSL 不支持 systemd可以在~/.bashrc末尾加一行启动脚本sudo service redis-server start这样每次登录终端时都会自动启动。但要注意这种写法如果不配合免密 sudo会每次提示输入密码。更稳妥的办法是在/etc/sudoers.d/下添加一条无密码执行 Redis 服务的规则sudo visudo -f /etc/sudoers.d/redis # 写入你的用户名 ALL(ALL) NOPASSWD: /usr/sbin/service redis-server *这是我实际用起来比较顺手的组合强烈推荐把redis-server和redis-cli都添加到 PATH 里方便在 VS Code 终端里随手敲命令。5.5 关于 WSL 网络异常的几个补充最后补充一个排查思路。如果你发现 WSL 里能访问外网但 Windows 连不上 WSL 里的服务先检查这三项# 1. 看看 localhost 转发是否生效 wsl --status # 2. 检查 Windows 防火墙是否拦截 # 在允许应用通过防火墙里确保 Vmmem 和对应 Ubuntu 发行版被允许 # 3. 手动指定 localhostForwarding # 在 .wslconfig 里写上 localhostForwardingtrue 后重启 WSL我在实际使用中还遇到过一个有意思的场景折腾完 Redis 之后再去跑别的服务比如在 WSL 里启动 Elasticsearch 或 Docker发现端口互相冲突。建议 WSL 里各服务端口做好规划Redis 用默认的 6379 没问题但 Elasticsearch、Docker 容器映射的端口尽量避开常见端口段能省掉不少麻烦。这一套环境现在是我日常开发的主力。最开始我以为问题出在 Windows 不支持 WSL后来才发现只是版本和功能组件的叠加问题把 WSL 2 装好、Redis 配置理顺之后Windows 下做 Linux 侧的开发体验完全不输纯 Linux 机器数据放在 Ubuntu 文件系统里也不用担心跨系统读写拖慢速度。如果你也在安装过程中卡住先对照这篇文章把前置检查和残留清理做一遍比反复卸载重装靠谱得多。
