在 Windows 的 PowerShell 窗口里敲下wsl回车一个 Linux 终端就出现在你面前这事听起来像魔法但底层就是 WSLWindows Subsystem for Linux在做转换。很多人想跑 GitHub 上的开源项目结果发现 README 里写的全是 Linux 那套命令装依赖、编译、启动脚本Windows 下硬凑环境不是不行但总会遇到各种别扭。与其在 PowerShell 里折腾一堆模拟器不如直接从 PowerShell 进入 Linux 环境再用这个环境去跑 GitHub 下载的项目。这篇文章就是围绕这条路径写的。不绕弯子不走 GUI把操作链路拆开讲清楚为什么用 WSL、怎么在 PowerShell 里把环境装起来、怎么把仓库拉下来、怎么根据项目类型跑起来、踩坑了怎么排查。适合两类读者一是刚接触 Linux 想在 Windows 里试试看的同学二是在 Windows 上做开发但项目必须在 Linux 下才能跑顺的从业者。1. 为什么选择 PowerShell 加 WSL 这条路1.1 同样是 Linux 环境WSL 和虚拟机差在哪先解决一个方向性问题想用 Linux方案有很多虚拟机、双系统、云服务器都能干为什么偏偏要在 PowerShell 里用 WSL虚拟机比如 VMware、VirtualBox给的是完整硬件模拟你在里头装一个完整的 Linux 系统隔离程度高但代价是资源开销大。你给它分 4GB 内存它就实打实吃掉 4GB启动要等开机流程日常切进切出也不够顺滑。双系统就更不用说了重启切换两个系统不能同时在线想从 Linux 里访问 Windows 的某个文件还得挂载分区折腾。WSL 走的是一条轻量路线。WSL2 实际上是微软在 Windows 里内置的一个轻量虚拟机但一般使用看起来就像本地终端。你从 PowerShell 里敲一条 wsl 命令秒开一个 Bash 环境没有 BIOS 界面没有开机动画不需要给虚拟机配内存显存网卡。更妙的是文件和网络天然打通你在 WSL 里可以直接看到C:盘挂载在/mnt/c下端口也能和 Windows 共享跑个 Web 服务后浏览器直接 localhost 就能访问。这种体验是传统虚拟机比不了的。对跑 GitHub 项目这个场景来说大部分开源项目其实都是命令行工具、Web 服务、脚本类项目并不需要完整的 Linux 桌面环境。WSL 提供的就是这种刚刚好的环境进程瞬间起来输入输出直接显示在终端里和 Linux 服务器几乎无差别。真遇到需要图形界面的项目WSLg 在 Windows 11 上也能把 Linux 的 GUI 程序带起来日常够用。1.2 版本选择WSL1 还是 WSL2WSL 有两个大版本很多人装完了都没意识到自己用的是哪个。WSL1 在设计上是一个翻译层把 Linux 的系统调用翻译成 Windows 内核调用兼容性一般文件访问速度倒是很快。WSL2 则是一个真正的轻量虚拟机上面跑着完整的 Linux 内核兼容性大幅提升主流开发场景都推荐用 WSL2。怎么确认自己用的是哪个在 PowerShell 执行wsl --status wsl --list --verbose如果显示VERSION: 2那就是 WSL2。如果是 1可以升级wsl --set-version Ubuntu-22.04 2升级过程需要一两分钟期间会提示重启照着来就行。以后默认装新发行版时建议把默认版本设为 2wsl --set-default-version 2版本统一很重要。很多 GitHub 项目依赖 Docker、需要 systemd 管理服务、或者用到了某些内核特性这些在 WSL2 下才顺。只是简单跑个翻目录脚本的话WSL1 区别不大但没必要开局就选一个会给自己添堵的版本。2. 在 PowerShell 里把 WSL 环境装好2.1 安装前先看两件事WSL 的安装门槛现在已经很低了Windows 10 版本 2004 往上或者 Windows 11基本都支持。安装之前检查两件事第一PowerShell 要以管理员身份运行。右键开始菜单选“终端(管理员)”或者“Windows PowerShell(管理员)”不要用普通窗口否则安装命令会报权限错误。第二确认 Windows 的虚拟化功能是开着的。这个一般在 BIOS 里设置名字叫 Intel VT-x 或 AMD SVM不同主板叫法不一样。如果没开wsl --install 装完可能启动不了显示让你开启虚拟化的错误。可以在 PowerShell 里执行systeminfo看底部的 Hyper-V 要求如果显示“已在固件中启用虚拟化”说明没问题。许多品牌电脑默认开启了虚拟化但偶尔有机器出厂默认关闭装完 WSL 起不来的同学优先查 BIOS。还有个容易被忽略的点不要从网上下载乱七八糟的安装脚本。网上流传的“一条命令安装 XXX”确实能装但来历不明的 PowerShell 脚本风险很大。irm | iex这种管道执行远程脚本的方式我一般只用在官方文档明确给出的来源上其他人分享的、来路不明的脚本一律不碰。WSL 本身是 Windows 内置功能官方命令足够不需要额外工具。2.2 一条命令完成安装并进入 Linux确认以上两点后在管理员 PowerShell 里执行wsl --install -d Ubuntu-22.04-d指定发行版。如果不想指定直接wsl --install会装默认发行版目前默认是 Ubuntu。装完系统会提示重启重启之后会自动弹出一个 Ubuntu 控制台窗口让你设置 Linux 用户名和密码。这个用户名是你日常使用的账号不是 root但会自动拥有 sudo 权限。密码输入时屏幕上不显示字符是正常的不要以为自己没敲进去。装完怎么进入其实从任何一个 PowerShell 窗口里都可以wsl这个命令进入默认发行版的交互式 Bash。如果你装了多个发行版想指定某个wsl -d Ubuntu-22.04想直接在 PowerShell 里执行一句 Linux 命令而不进入交互式 shell可以wsl -e bash -lc ls -la /home这个方式很实用写脚本、做定时任务、在构建系统里调用 Linux 命令都用得上。比如从 PowerShell 里查看 Linux 侧的当前目录wsl -e pwd它会直接打印 Linux 路径然后回到 PowerShell。这是两种使用模式交互式和单发式。日常调试用交互式自动化任务用单发式。2.3 装好之后建议立刻调的三件小事环境装好不代表万事大吉我每次在新机器上装完 WSL 都会顺手做三件事能省后面非常多的麻烦。第一把软件源换成国内可访问的镜像。Ubuntu 默认官方源在国外apt update和装依赖经常无故超时尤其当 GitHub 项目需要几十个依赖包时卡在某个 apt 源上会非常折磨。换源不复杂备份原文件然后替换。Ubuntu 22.04 及更早版本编辑/etc/apt/sources.listUbuntu 24.04 起源文件改成了 deb822 格式位置在/etc/apt/sources.list.d/ubuntu.sources。我先说通用的老格式写法sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list sudo apt update24.04 的 deb822 格式是把文件里的URIs: http://archive.ubuntu.com/ubuntu/替换成URIs: http://mirrors.tuna.tsinghua.edu.cn/ubuntu/再清理一下后缀的镜像标识sudo sed -i s|http://archive.ubuntu.com/ubuntu/|http://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources sudo apt update换成清华源、阿里源都行本质是让包下载链路更稳定。不要问“官方源能用为什么要换”等你亲眼看到 apt 卡在连接超时上的时候就明白了。第二执行系统更新把内核和基础软件拉齐sudo apt update sudo apt upgrade -y这一步会让后续装依赖少报一堆版本不兼容的错误。第三确认 WSL2 的内核和组件是最新的。在 PowerShell 里wsl --updateWSL 本体更新很频繁旧版本可能不支持 systemd 或者新发行版。保持更新是成本最低的避坑方法。3. 进入 Linux 后如何把 GitHub 项目跑起来3.1 动手前先花五分钟看清项目很多人拿到 GitHub 项目第一反应就是 git clone然后一秒钟代码到手再然后就没有然后了——不知道装什么依赖不知道该执行哪个文件。问题不在于命令不会敲而在于没先看清项目的“说明书”。打开 GitHub 项目主页第一个看的是 README。它一般会告诉你这是什么、环境要求、安装步骤、运行方式。README 里提到 Node.js 版本、Python 版本、编译依赖都是硬性要求缺一个都跑不起来。第二个看根目录下的文件列表。看到package.json说明是 Node.js 项目看到requirements.txt或pyproject.toml说明是 Python 项目看到CMakeLists.txt或Makefile说明需要编译看到 Dockerfile说明可以用容器跑那又省事不少。这些文件本身就是“路标”比任何教程都准确。第三个跑不起来时别急着乱改代码先去 Issues 里搜一下报错关键词。开源项目的坑往往已经被前人踩过很多问题在 Issues 里反复出现搜得快比别人自己捣鼓一小时高效。3.2 从 GitHub 拉取代码的完整流程看清楚了就可以拉代码了。在 WSL 的 Linux shell 里git clone https://github.com/用户名/仓库名.git建议先建一个专用目录把项目统一放进去后面好找也好维护mkdir -p ~/projects cd ~/projects git clone https://github.com/用户名/仓库名.git cd 仓库名这里有个小细节很多人习惯直接在 Windows 桌面或者 D 盘右键下载 zip 解压然后再想办法弄进 WSL。其实没必要。WSL 能直接访问 Windows 文件系统Windows 下载的 zip 压缩包在/mnt/d/你的文件夹/xxx.zip里能找到用tar解压到 Linux 侧就行。但更好的做法是让 Linux 侧的 git 自己拉这样后续git pull升级项目版本也方便不会出现“更新只能重下压缩包”的尴尬。如果你的网络直连 GitHub 不稳定clone 可能中途失败。两个急救方案一是只克隆最新一次提交历史提交记录不要了git clone --depth 1 https://github.com/用户名/仓库名.git二是项目不大的话直接在 GitHub 网页上下载 zip然后在 Linux 里解压cd ~/projects unzip /mnt/c/Users/你的用户名/Downloads/仓库名-main.zip仓库名-main.zip是 GitHub 默认的下载包名解压出来的目录名一般是仓库名-main看得到就行。3.3 三类常见项目分别怎么跑我拆三类最常见的覆盖大部分 GitHub 热门项目。第一类Python 项目。进入项目目录后先建虚拟环境不要直接往系统里装依赖python3 -m venv venv source venv/bin/activate pip install -r requirements.txt python main.py.venv或venv是虚拟环境目录相当于一个隔离的 Python 空间。为什么不直接用系统 Python因为不同项目可能依赖同一库的不同版本共用系统环境会在项目之间打架。虚拟环境把依赖锁在项目内换项目不冲突这是从业者默认操作。如果项目没有 requirements.txt就看 README 里写了什么安装命令。如果没有查看主入口文件头部 import 了什么逐个安装。第二类Node.js 项目。WSL 里不一定自带 Node建议用 nvm 管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20然后npm install npm run dev或者根据 README 里的说明执行npm start、node index.js之类的命令。nvm 的作用和 Python venv 类似它是让同一台机器上可以同时存在多个 Node 版本项目要求什么版本就切换什么版本避免“升级 Node 把老项目搞挂”。第三类需要编译的项目C/C、Rust。除了项目本身的 README 要求系统层需要编译工具链sudo apt install -y build-essential cmakeCMake 项目常见的四步流程cmake -S . -B build cmake --build build ./build/生成的程序名Rust 项目则是cargo run --release这类项目的编译时间通常比较长第一次跑别急。如果中途报缺库记住缺什么就apt install什么比如缺libssl-dev装上再重新编译。3.4 Windows 和 Linux 文件系统怎么互通WSL 一个很大的卖点是文件互通。Windows 的整个盘符都挂在 Linux 的/mnt下C 盘是/mnt/cD 盘是/mnt/d。反过来Linux 的主目录在 Windows 侧可以通过资源管理器路径\\wsl$\Ubuntu-22.04\home\你的用户名访问。这种互通的代价是性能差异。跑大项目、做大量小文件读写时放在/mnt/c下的代码会明显比放在 Linux 主目录里慢因为中间隔了一层文件系统转换。常见误区是把项目 clone 到 Windows 的 D 盘再在 WSL 里进入/mnt/d/项目名去跑虽然能运行但速度肉而且可能触发文件锁相关的问题。我个人的习惯是项目代码永远放 Linux 侧比如~/projects需要用 Windows 侧数据时再通过/mnt/c读取。路径转换也是个高频问题。项目里写死了某个 Windows 路径比如C:\Users\me\data在 Linux 里要用/mnt/c/Users/me/data。反向操作时用wslpath工具可以自动转换wslpath C:\Users\me\data输出/mnt/c/Users/me/data。在 Windows 侧想快速复制 Linux 路径也可以在 PowerShell 里用wslpath -w /home/you/projects会输出\\wsl$\Ubuntu-22.04\home\you\projects这种 Windows 格式路径粘贴到哪里都好使。4. 跑 GitHub 项目时容易踩的坑4.1 依赖下载太慢或超时别只会傻等GitHub 项目跑起来之前的第一个敌人是依赖下载。npm、pip、apt 各自都有包源访问境外地址时快慢看运气。我的处理原则很直接能用国内镜像就在项目配置里临时指定少折腾整体环境。pip 临时换源安装的时候加-i参数pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplenpm 换源npm install --registryhttps://registry.npmmirror.comapt 的源在上面已经换过了。这三个是跑项目时最常遇到的三个包管理器全部都有成熟的镜像方案。注意换源只影响下载这一环不会改变代码逻辑也不影响项目本身放心用。git clone 本身慢的时候除了镜像网站还有一个很实用的思路先去 GitHub 网页下载 zip再在 Linux 侧解压。zip 下载走的是 CDN 链路和 git 协议传输走的不是一条路有时候 git 死活拉不动zip 反而秒下。项目跑起来后如果需要更新可以用git pull或者干脆重新解压替换视你的使用频率决定。4.2 权限和换行符这两个问题容易被忽略跑脚本时最经典的一个报错是这个bash: ./script.sh: Permission denied原因很简单文件没有执行权限。GitHub 上下载的 zip 或者从 Windows 复制过来的文件经常丢掉 Unix 的执行权限位。解决方式chmod x script.sh ./script.sh只要文件具备执行权限./xxx才能跑这是 Linux 的基本安全设计。很多人从 Windows 转过来不习惯记住这个组合拳即可。更隐蔽的问题是换行符。Windows 文本文件的换行是 CRLF回车换行而 Linux 只认 LF。如果你在 Windows 上用记事本编辑过脚本、配置文件再传到 Linux 里跑会报各种诡异错误最常见的现象是$\r: command not found。处理方式有两个。一个是安装 dos2unix 批量转换sudo apt install dos2unix dos2unix script.sh更根本的做法是项目代码和配置文件都尽量在 Linux 侧直接编辑。用 VS Code 连上 WSL 就是很好的一种操作习惯打开的目录是 Linux 路径编辑器处理的就是 Linux 风格的换行符不会引入跨平台的坑。4.3 依赖缺失和版本冲突识别报错是关键依赖相关的问题占整个踩坑比例一大半。我把它们的报错形式和应对逻辑整理成一个速查表报错特征通常原因处理方式ModuleNotFoundError: No module named xxx缺少 Python 库pip install xxx或安装 requirements.txtcommand not found: npm / nodeNode 未安装用 nvm 安装指定版本error: libxxx not found系统缺少编译依赖apt install libxxx-devPermission denied没有执行权限chmod x 文件Address already in use端口占用ss -tlnp查端口并关掉占用进程Cant connect to server服务没起来或网络配置错误检查服务日志和端口监听地址依赖版本冲突是更麻烦的一种。项目 A 要求 Python 库 X 的 1.0 版本项目 B 要求 2.0共用环境就是灾难。这就是前文反复强调虚拟环境的原因。不要嫌麻烦python3 -m venv venv一行命令的事换来的是一劳永逸的隔离。另一条经常被忽视的原则不要随便升级依赖版本。项目 README 里写死版本一定有其原因跑不起来时先怀疑环境配置不要第一反应就是升级所有包。我在实际项目中就吃过亏把某个库升到新版项目之前正常升级后直接启动失败最后回滚版本才解决。在开源项目里“能用就保持原样”是美德。4.4 服务起来了但浏览器访问不了项目是 Web 服务的时候常遇到的困惑是Linux 侧明明打印了“Server running at http://127.0.0.1:8080”Windows 浏览器访问 localhost:8080 却打不开。WSL2 默认是支持通过 localhost 访问 Linux 侧服务的但有一个前提服务要监听在所有网卡地址上也就是0.0.0.0:8080或者0.0.0.0而不是只监听127.0.0.1。很多项目默认监听 127.0.0.1这在 Linux 内部访问没问题WSL 的端口转发到 Windows 侧却不一定能通。改法一般是在启动参数里加--host 0.0.0.0或者环境变量HOST0.0.0.0具体看项目文档。如果改完还访问不了先确认服务是不是真起来了ss -tlnp | grep 8080看监听地址到底是不是0.0.0.0。再排查 Windows 防火墙是否是拦截了 WSL 转发端口加了端口转发规则还不行就直接在 PowerShell 里重启一下 WSLwsl --shutdown然后再wsl进入重新把服务跑起来。这个操作能解决不少偶发的网络转发问题原理是 WSL2 重启后网络配置会重新初始化。Linux 侧的 IP 在 WSL2 每次启动时都可能变Windows 侧的端口转发是基于动态机制的偶发不通时重启它就是最快的解法。4.5 PowerShell 侧的小毛病乱码和命令无法识别整个流程里面还有一个容易让人愣住的场景存在于 PowerShell 自身。比如从 PowerShell 进入 Linux 后运行一个输出中文的程序结果终端里全是乱码。这是 Windows 控制台的代码页和 Linux 侧 UTF-8 不一致导致的。改法是在 PowerShell 里执行chcp 65001将当前控制台代码页设为 UTF-8乱码立即解决。更一劳永逸的方式是把 Windows Terminal 的默认编码设为 UTF-8打开设置在配置文件 - 默认 - 外观里把字符集改对或者在“区域设置”里给“Beta使用 Unicode UTF-8 提供全球语言支持”打勾改完需要重启。还有那个高频报错在 PowerShell 里输入cd或Set-Location时提示“无法将‘set-location’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这通常不是你敲错命令而是 PowerShell 的 PATH 环境变量被篡改导致 PowerShell 自己都找不到内置命令。排查方式检查系统环境变量里 PATH 是否包含C:\Windows\System32\WindowsPowerShell\v1.0\。修复方式是在系统设置中补回这个路径或者用管理员 PowerShell 执行[Environment]::SetEnvironmentVariable(Path, $env:Path;C:\Windows\System32\WindowsPowerShell\v1.0\, Machine)然后重开 PowerShell。另外如果是从网页或者聊天工具复制的cd命令注意看有没有混入全角字符或者隐藏格式符全角的逗号、空格看起来像命令实际不是。这类问题的定位思路就是先怀疑路径、再怀疑格式、最后怀疑环境变量。5. 常见问题速查表和个人使用习惯5.1 把高频问题整理成一张速查表整个链路走下来我用一张表把最容易卡住人的问题收进同一下图表方便直接对照问题现象出现环节处理方法wsl: 未安装或命令找不到安装管理员 PowerShell 执行wsl --install -d Ubuntu-22.04powershell cd无法识别为 cmdletPowerShell检查 PATH 是否包含 PowerShell 目录重开终端中文乱码PowerShell/终端chcp 65001改用 Windows TerminalPermission denied执行脚本chmod x 脚本名$\r: command not found跨平台编辑dos2unix 文件或改用 VS Code 在 WSL 里编辑ModuleNotFoundErrorPython 项目在虚拟环境里pip install -r requirements.txtgit clone 拉取失败下载试--depth 1或用浏览器下载 zip 解压依赖下载超时安装依赖pip/npm 换镜像源端口被占用启动服务ss -tlnp找到进程并结束浏览器打不开 localhost启动服务服务监听改为0.0.0.0wsl --shutdown重启链路项目在/mnt/c下跑得慢运行把项目移到~/projects下再运行这个方法的核心不是记住每个命令而是掌握一个排错路径看到报错先识别它属于安装、权限、依赖、网络里的哪一环然后对症处理。大部分 GitHub 项目的报错都不是“你代码写得有问题”而是“环境还差一个条件”。5.2 我的几个使用习惯最后说几个我用顺了的小习惯不一定适合所有人但确实少踩了很多坑。第一项目目录统一放 Linux 侧。我习惯在 WSL 里建一个~/projects目录所有 GitHub 项目都放里面。好处是路径短、读写快、和 Windows 的权限系统隔开。虽然 WSL 文件互通好用但我已经吃过几次在/mnt/c下跑项目跑出莫名性能问题的亏普通脚本无所谓大项目尽量放 Linux 原生文件系统里。第二依赖环境隔离绝不混用。Python 项目一律用 venvNode 项目用 nvm 控制版本系统级 Python 和系统级 Node 尽量保持干净。做完一个项目把虚拟环境删了也不心疼下次要用按 README 重装就是。这种做法刚看起来占比多几步但长期维护多个项目的体验远远好于一个被装乱的系统环境。第三开机自启的 WSL 服务可以用任务计划程序管理。如果你跑的是一个需要常驻后端服务的项目比如自己编译部署的服务器程序在任务计划程序里创建一个开机触发任务操作填wsl -d Ubuntu-22.04 -u root -- 服务启动命令比如wsl -d Ubuntu-22.04 -u root -- service docker start这样开机后 WSL 就会在后台启动对应服务。注意不要在这个任务里写交互式 shell 命令否则开机时会弹出一个终端窗口体验很差。写成-e bash -lc 启动命令的静默执行形式更合适。第四遇到问题先搜 Issues再搜搜索引擎最后再改代码。开源项目的坑大部分是别人踩过的你遇到的那个“诡异现象”大概率在仓库 Issues 里已经有人讨论过了。学会用英文关键词搜效率更高。不要一上来就怀疑项目本身有问题先假定是自己的环境没对齐。我最初开始用 WSL 的时候也是从 PowerShell 里敲wsl开始一路踩坑到现在摸出了一套自己的节奏。如果你也是从 Windows 出发想去 Linux 侧跑 GitHub 项目我的建议是找一个小的命令行项目先跑通全流程不要第一次就挑战那种依赖一大串、需要编译半天的大项目。小项目把链路摸顺了后面遇到大项目时问题无非是依赖多一点、编译久一点但流程逻辑是一样的。等这套环境用顺手了你大概率会和我一样把 WSL 当成日常开发里离不开的一层入口。