WSL + Pygame：AI极简生成超级马里奥小游戏实战指南

之前折腾 AI 生成小游戏的时候踩了不少环境上的坑提示词写得不够收敛模型会东补一块西补一块生成完之后又发现 Windows 本机跑 Linux 依赖特别麻烦。后来把工作流切到 WSL 下用“极简模式 一轮生成”的方式去生成一个超级马里奥小游戏整个过程顺畅了很多。这篇文章就把这套流程完整拆开从 WSL 环境准备、极简提示词设计到完整 Pygame 代码运行再到高频报错排查一次性讲清楚。如果你也想在 Windows 上跑 Linux 开发环境或者想尝试用 AI 生成小游戏但不想被环境问题劝退这篇实战笔记可以收藏备用。文章里涉及的所有命令都是基于常见 WSL 2 环境版本差异部分我会单独说明照着做基本都能跑起来。1. 背景与核心概念1.1 什么是 WSL 以及为什么要用 WSLWSL 全称是 Windows Subsystem for Linux也就是 Windows 提供的 Linux 子系统。通俗地说它让你在 Windows 里面直接运行一个 Linux 发行版比如 Ubuntu而不需要装虚拟机或者双系统。WSL 2 是第二代实现底层使用真正的 Linux 内核兼容性比第一代好很多是目前最常用的版本。为什么开发小游戏要用 WSL主要原因有三点AI 生成代码时经常默认给出 Linux/macOS 环境的安装命令比如apt、pip3、python3在 WSL 里可以直接执行不需要翻译成 Windows 命令。WSL 文件系统与 Windows 互通生成的代码可以在两边共享VSCode 也能无缝连接。WSL 比虚拟机轻量启动快、内存占用小适合做“生成 → 运行 → 改 bug”这种高频迭代。很多读者分不清 WSL 和虚拟机的区别虚拟机是完整模拟一台电脑开销大WSL 2 是 Windows 与 Linux 内核之间做了轻量集成文件访问更快启动几乎瞬间完成。日常做 Python 小游戏、脚本开发、AI 生成代码验证WSL 是性价比最高的选择。1.2 “极简模式 一轮生成”是什么意思“极简模式”指的是提示词设计上做减法。很多人用 AI 生成游戏时会写一大堆需求描述结果模型反而抓不住重点生成的代码要么逻辑混乱要么结构冗余。极简模式的思路是只给出最核心的运行环境、功能范围和交付格式让模型把精力放在“写出一份能跑通的代码”上。“一轮生成”则是对迭代方式的约束。常见做法是让 AI 反复改需求、多次对话调试这样虽然也能得到结果但耗时长、不稳定。一轮生成的意思是通过结构化提示词让 AI 在首次输出就给出接近完整的代码后续只做少量修复而不是从零到一反复重写。要做到一轮生成关键不是提示词越长越好而是信息层次清晰。后面第 3 章我会给出可直接套用的提示词模板。1.3 本次项目的目标与最终效果本次项目代号是 “v4 pro-0813”内部含义就是在 0813 这个时间节点用某一版新模型在“极简模式”下完成超级马里奥小游戏的生成。整个流程的核心链路是Windows WSL2 Ubuntu Python3 Pygame最终你会得到一个类似这样的成果窗口中出现一个横版 2D 小游戏玩家可以控制角色左右移动和跳跃跳过障碍、踩敌人到达终点旗帜后胜利。代码量不大但包含完整游戏循环、键盘输入、碰撞检测、胜负条件是学习 Pygame 和 AI 生成代码非常好的练手项目。2. 环境准备WSL 安装与 Python 配置2.1 安装前的检查项在开始装 WSL 之前建议先确认三件事Windows 10 版本号不低于 2004或者使用 Windows 11这样 WSL 2 支持更完整。电脑 BIOS 中开启了虚拟化功能Intel 平台一般是 Intel VT-xAMD 平台是 SVM Mode。磁盘剩余空间至少 20GBWSL 的虚拟磁盘文件会占用数 GB 空间。检查虚拟化是否开启可以在管理员 PowerShell 中执行systeminfo输出信息里有一项 “Hyper-V 要求”如果显示“已检测到虚拟机监控程序将不显示 Hyper-V 所需的功能”说明虚拟化已经启用如果显示“固件中已启用虚拟化”为“否”就需要重启电脑进入 BIOS 打开虚拟化开关。2.2 使用 wsl --install 安装 Ubuntu从 Windows 10 2004 开始微软提供了最简单的一键安装命令。在管理员 PowerShell 或 CMD 中执行wsl --install这个命令会默认安装 WSL 2 和一个 Ubuntu 发行版。如果已经安装过 WSL想指定其他发行版可以用wsl --install -d Ubuntu-22.04安装完成后重启电脑第一次启动 Ubuntu 时需要设置用户名和密码。需要注意wsl --install依赖微软服务器如果网络环境不稳定可能出现“无法与服务器建立连接”“wsl needs updating”等报错。这种情况可以分两步处理第一步手动更新 WSL 内核wsl --update第二步如果在线下载仍然失败可以尝试离线导入方式。先在微软官网下载 Ubuntu WSL 安装包后缀为.appx或.tar.gz然后使用wsl --import导入例如wsl --import Ubuntu-DIY D:\WSL\Ubuntu-DIY D:\download\ubuntu.tar.gz --version 2这种离线方式适合服务器环境或网络受限场景Windows Server 2022 离线部署 WSL 容器也可以参考这个思路。2.3 配置 Ubuntu 中的 Python 与 pipUbuntu 22.04 默认自带 Python 3.10一般不需要手动安装 Python。但需要确认pip和venv是否可用python3 --version pip3 --version如果提示pip3不存在先执行sudo apt update sudo apt install -y python3-pip python3-venv这里有一个工程上的好习惯不要全局安装 Python 包而是为每个项目创建独立虚拟环境。这样不同项目之间的依赖不会互相污染。2.4 安装 PygamePygame 是 Python 的 2D 游戏开发库封装了图形绘制、事件监听、碰撞检测等能力非常适合做超级马里奥这种横版小游戏。进入项目目录后创建虚拟环境并安装 Pygamemkdir -p ~/projects/mario cd ~/projects/mario python3 -m venv .venv source .venv/bin/activate pip install pygame国内网络环境下如果官方 PyPI 下载慢可以临时使用清华镜像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pygame如果不确定 Pygame 是否安装成功可以在 Python 中验证python3 -c import pygame; print(pygame.version.ver)如果正常输出版本号说明环境已经就绪。2.5 在 VSCode 中连接 WSL这一步不是必须的但强烈推荐。VSCode 安装 WSL 扩展后可以直接在 Windows 窗口里编辑 WSL 内的文件终端也会自动连接到 WSL 环境省去手动切换的麻烦。操作步骤在 VSCode 扩展市场安装 “WSL” 扩展。打开命令行输入wsl进入 Ubuntu 环境。在项目目录执行code .VSCode 会自动以 WSL 模式打开当前目录。这样做的最大好处是代码在 Linux 文件系统里运行、调试也在 Linux 环境避免 Windows 与 Linux 路径转换引发的各种小问题。3. 极简提示词如何让 AI“一轮”给出游戏代码3.1 一轮生成和多轮迭代的区别很多开发者让 AI 生成游戏代码习惯是“先生成一个版本然后不断提修改需求”比如“角色太慢了改快一点”“加一个敌人”“背景换成黑色”。这种做法不是不行但当生成内容从几十行膨胀到几百行时AI 很容易在后续修改中破坏原有逻辑导致需要反复修复。一轮生成的思路是提前把所有关键需求封装在提示词里让 AI 一次性输出完整代码。提示词表达的信息越明确生成结果越接近可运行状态。它更适合小体量的项目比如单文件 Pygame 游戏、命令行工具、脚本等。3.2 极简提示词模板下面这个提示词模板是本次实践的核心可以直接复制使用。它的特点是只约束“环境、功能、结构”三项不限制具体美术资源或复杂玩法。请用 Python 和 Pygame 写一个超级马里奥风格的 2D 横版小游戏要求 1. 使用 pygame 库代码全部放在一个 mario.py 文件中 2. 玩家角色是一个彩色方块可以按方向键左右移动按空格键跳跃 3. 地图包含地面、若干个可站立平台、至少一个移动敌人 4. 角色踩到敌人则游戏结束到达场景右侧的旗帜则胜利 5. 包含窗口初始化、游戏主循环、事件监听、碰撞检测、文字提示 6. 代码结构清晰有必要的注释确保 Python 3 环境可以直接运行 7. 运行时不需要额外加载图片资源全部用 pygame.draw 绘制。这个提示词的关键点在于“全部用 pygame.draw 绘制”它避免 AI 去生成图片路径或外部素材让游戏代码变成真正的“单文件可运行”。这也是极简模式的核心诉求降低运行门槛提高一次成功率。3.3 拿到生成代码后先检查哪些东西AI 生成完代码之后不要急着直接运行先做一个一分钟人工检查import 语句是否正确只依赖pygame和sys这类标准库。是否有硬编码的图片路径、字体文件路径。主循环里是否有pygame.event.get()和pygame.display.flip()。碰撞检测是否基于pygame.Rect而不是随意的手写坐标判断。窗口尺寸是否合理比如 800x600 或 640x480。如果以上检查都通过基本可以运行如果运行时报错优先看报错信息的前三行多数问题集中在缺少依赖、缩进错误、变量名未定义这三类。4. 完整实战在 WSL 中生成并运行超级马里奥4.1 创建项目结构首先在 WSL 中创建项目目录。打开终端进入 Ubuntu 环境mkdir -p ~/projects/mario cd ~/projects/mario项目的最终结构如下~/projects/mario/ ├── .venv/ # Python 虚拟环境 └── mario.py # 游戏主程序本文示例中只有一个核心代码文件方便演示“一轮生成”的最小闭环。如果你在实际项目中希望扩展更多功能再考虑拆分成player.py、enemy.py、level.py等多个模块。4.2 核心代码mario.py下面这份代码是本次“极简模式”生成目标的等效实现。为了保证文章可以直接复现我把代码整理成完整可运行的版本并添加了必要注释。# 文件路径~/projects/mario/mario.py import sys import pygame # 初始化 Pygame pygame.init() # 窗口与游戏参数 SCREEN_WIDTH 800 SCREEN_HEIGHT 600 FPS 60 GRAVITY 0.8 JUMP_POWER -15 PLAYER_SPEED 5 ENEMY_SPEED 2 # 颜色定义 SKY_BLUE (135, 206, 235) GROUND_BROWN (139, 90, 43) PLATFORM_BROWN (101, 67, 33) PLAYER_BLUE (30, 144, 255) ENEMY_RED (220, 20, 60) FLAG_ORANGE (255, 165, 0) WHITE (255, 255, 255) BLACK (0, 0, 0) class Player: 玩家角色用蓝色方块表示。 def __init__(self, x, y): self.rect pygame.Rect(x, y, 32, 32) self.vel_x 0 self.vel_y 0 self.on_ground False def move_left(self): self.vel_x -PLAYER_SPEED def move_right(self): self.vel_x PLAYER_SPEED def stop(self): self.vel_x 0 def jump(self): if self.on_ground: self.vel_y JUMP_POWER self.on_ground False def update(self): # 应用重力 self.vel_y GRAVITY self.rect.x self.vel_x self.rect.y self.vel_y def draw(self, screen): pygame.draw.rect(screen, PLAYER_BLUE, self.rect) class Enemy: 移动敌人用红色方块表示碰到玩家则游戏结束。 def __init__(self, x, y): self.rect pygame.Rect(x, y, 28, 28) self.direction 1 def update(self): self.rect.x ENEMY_SPEED * self.direction # 在平台范围内往返移动 if self.rect.x 500 or self.rect.x 700: self.direction * -1 def draw(self, screen): pygame.draw.rect(screen, ENEMY_RED, self.rect) class Game: 主游戏类负责窗口、碰撞、胜负逻辑。 def __init__(self): self.screen pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT)) pygame.display.set_caption(Mario - WSL Edition) self.clock pygame.time.Clock() self.font pygame.font.Font(None, 36) self.player Player(80, 400) self.enemy Enemy(550, 372) self.platforms [ pygame.Rect(0, SCREEN_HEIGHT - 40, SCREEN_WIDTH, 40), # 地面 pygame.Rect(300, 450, 150, 20), # 平台1 pygame.Rect(520, 360, 120, 20), # 平台2 ] self.flag pygame.Rect(760, 500, 20, 100) # 终点旗帜 self.game_over False self.win False def handle_events(self): for event in pygame.event.get(): if event.type pygame.QUIT: pygame.quit() sys.exit() if event.type pygame.KEYDOWN: if event.key pygame.K_SPACE: self.player.jump() # 持续按键控制左右移动 keys pygame.key.get_pressed() if keys[pygame.K_LEFT]: self.player.move_left() elif keys[pygame.K_RIGHT]: self.player.move_right() else: self.player.stop() def check_collisions(self): player self.player # 默认先假设玩家不在碰撞的地面上 player.on_ground False for plat in self.platforms: if player.rect.colliderect(plat): # 只处理从上方落到平台的情况 if player.vel_y 0 and player.rect.bottom plat.bottom 10: player.rect.bottom plat.top player.vel_y 0 player.on_ground True # 从下方顶到平台时阻止角色继续上升 elif player.vel_y 0 and player.rect.top plat.top - 10: player.rect.top plat.bottom player.vel_y 0 # 遇到敌人则游戏结束 if player.rect.colliderect(self.enemy.rect): self.game_over True # 到达旗帜则胜利 if player.rect.colliderect(self.flag): self.win True def update(self): if not self.game_over and not self.win: self.player.update() self.enemy.update() self.check_collisions() # 防止角色掉落屏幕外 if self.player.rect.top SCREEN_HEIGHT: self.game_over True def draw(self): self.screen.fill(SKY_BLUE) # 画地面和平台 for plat in self.platforms: pygame.draw.rect(self.screen, GROUND_BROWN, plat) # 画敌人和玩家 self.enemy.draw(self.screen) self.player.draw(self.screen) # 画终点旗帜 pygame.draw.rect(self.screen, FLAG_ORANGE, self.flag) flag_text self.font.render(FLAG, True, BLACK) self.screen.blit(flag_text, (self.flag.x 25, self.flag.y 35)) # 画游戏状态提示 if self.game_over: text self.font.render(GAME OVER - Press R to restart, True, WHITE) self.screen.blit(text, (200, 280)) elif self.win: text self.font.render(YOU WIN! - Press R to restart, True, WHITE) self.screen.blit(text, (200, 280)) pygame.display.flip() def run(self): while True: self.handle_events() keys pygame.key.get_pressed() if keys[pygame.K_r] and (self.game_over or self.win): self.__init__() self.update() self.draw() self.clock.tick(FPS) if __name__ __main__: game Game() game.run()这份代码的结构是“类 主循环”三个类分别对应玩家、敌人、游戏主体。Pygame 的核心逻辑都在Game类中handle_events处理键盘输入update更新物理与碰撞draw负责绘图。这种分层方式也符合工程化习惯方便后续扩展。有一个地方需要留意run()方法里按 R 键重置游戏时我直接调用了self.__init__()。在真实项目中更推荐单独写一个reset()方法避免重复初始化窗口。这里为了代码简短保留了这种写法读者可以根据实际需要优化。4.3 运行与验证在 WSL 终端中确保虚拟环境已激活然后运行python mario.py如果是在 Windows 11 且系统支持 WSLg会直接弹出一个图形窗口如果是在 Windows 10 或没有 WSLg 的环境中可能无法显示窗口这种情况下建议使用 Windows 侧的 Python 环境运行或者参考第 5 章中的 GUI 排查方法。运行成功后会看到一个浅蓝色背景的窗口标题为 “Mario - WSL Edition”。地面是棕色长条中间分布两个平台。红色敌人左右移动。蓝色玩家方块可以左右移动按空格跳跃。触碰到敌人时显示 “GAME OVER”到达右侧橙色旗帜时显示 “YOU WIN”。4.4 修改与扩展思路如果你希望在“极简模式”生成结果的基础上继续扩展下面几个方向优先级最高多关卡把平台和敌人位置做成关卡列表通关后加载下一关。计分系统增加金币或得分方块吃到一个加十分。音效用pygame.mixer.Sound播放跳跃和吃金币的音效。角色贴图将绘制方块替换为精灵图片代码结构不需要大变。这些扩展在工程上的本质都是“增加数据 增加逻辑分支”对 Pygame 理解越深扩展越顺手。5. 高频问题与排查思路5.1 WSL 安装与更新类报错问题现象常见原因排查与解决提示 “wsl needs updating”WSL 内核版本过旧管理员 PowerShell 执行wsl --update然后重启终端wsl --install无法连接服务器网络波动或镜像不可达检查网络代理设置更换网络环境后重试仍失败则使用离线 tar 包 wsl --import错误码 14098WSL 服务状态异常执行wsl --shutdown然后重新启动 WSL安装 Ubuntu 后无法获取发行版信息系统区域或时间设置异常检查 Windows 时间是否为自动同步确保时区正确关于“wsl --install -d ubuntu-24.04 报错”这个问题网上讨论很多本质上多是因为虚拟化未开启或 WSL 内核过旧。先运行wsl --update再确认 BIOS 虚拟化已开启最后重新安装目标发行版。5.2 WSL 2 无法启动虚拟化未启用如果执行wsl --install -d ubuntu-24.04时提示“WSL2 无法启动因为此计算机上未启用虚拟化”说明 Hyper-V 或虚拟化固件没有就绪。处理步骤重启电脑进入 BIOS找到 “Intel Virtualization Technology” 或 “SVM Mode”设置为 Enabled。在 PowerShell 中检查 Windows 功能Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V如果状态为 Disabled可以启用 Hyper-V注意这会影响 Docker Desktop 的模式选择。执行bcdedit /set hypervisorlaunchtype auto开启系统的 Hypervisor 启动。需要注意的是修改后必须重启才能生效。如果是旧电脑不支持虚拟化只能退回 WSL 1但 WSL 1 对 Pygame 窗口和性能支持不如 WSL 2。5.3 GUI 窗口无法弹出Pygame 运行报错Pygame 是图形应用运行后必须弹出窗口。在 WSL 2 中窗口显示依赖 WSLg 组件。Windows 11 较新版本默认支持 WSLgWindows 10 的较新预览版也有支持但如果系统版本较旧窗口可能无法显示。排查顺序运行wsl --version查看 WSL 版本如果版本过低执行wsl --update。在 WSL 中执行echo $DISPLAYWSLg 正常情况下会输出一个本机回环地址而不是空值。如果只在一个 SSH 连接中运行 WSL可能会丢失图形转发建议直接在 VSCode 的 WSL 终端中运行。如果始终无法显示窗口最稳妥的方案是在 Windows 侧用 Python 运行同一份代码WSL 侧负责生成和调试代码。此外错误提示 “No video mode large enough for 800x600” 这类问题通常是因为窗口显示环境异常而不是代码问题。先解决 WSLg 再运行代码。5.4 pip 安装慢、超时或依赖冲突在国内网络环境下pip install pygame偶尔会非常慢。推荐使用国内 PyPI 镜像例如清华源或阿里源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pygame如果你已经安装过多个 Python 包出现依赖冲突的可能性不大因为 Pygame 本身依赖很少。但建议仍然使用虚拟环境隔离项目避免把包装到系统环境中。如果安装后导入 Pygame 出现ModuleNotFoundError先检查是否激活了正确的虚拟环境which python which pip确认 Python 和 pip 都指向.venv路径。5.5 Docker Desktop 更新后运行不了 WSL这个问题在社区中出现频率很高。Docker Desktop 依赖 WSL 2 后端如果更新 Docker Desktop 后提示 WSL 相关错误通常是 WSL 内核版本没有同步更新。解决方案是先在管理员 PowerShell 中执行wsl --update wsl --shutdown然后重新启动 Docker Desktop。如果依然失败检查 Docker Desktop 设置中的 “Use the WSL 2 based engine” 是否勾选。这里有一个容易混淆的概念WSL 的 NAT 模式与镜像模式。默认 NAT 模式下WSL 内的网络是独立子网Windows 访问 WSL 服务需要通过localhost转发镜像模式则可以共享 Windows 网络接口。对 Docker 容器端口映射来说NAT 模式基本够用如果遇到端口访问异常可以在.wslconfig中切换networkingModemirrored试试。6. 工程化建议让生成代码变成可维护项目6.1 用 .wslconfig 管理 WSL 资源WSL 2 默认可能占用较多内存尤其是运行多个发行版或 Docker 容器时。可以创建一个.wslconfig文件放在 Windows 用户目录下例如C:\Users\你的用户名\.wslconfig来控制资源上限[wsl2] memory4GB processors2 swap2GB localhostForwardingtrue注意配置修改后需要执行wsl --shutdown再重新进入 WSL 才会生效。这里的localhostForwardingtrue表示允许 Windows 通过 localhost 访问 WSL 内服务对 Pygame 这类本地应用影响不大但如果你以后跑 Web 服务会很有用。6.2 使用虚拟环境与依赖锁定即使只是一个小游戏也建议用虚拟环境。原因很简单生成代码时 AI 可能帮你引入“临时依赖”不隔离的话很容易污染系统 Python。完成项目后可以用下面的命令导出依赖pip freeze requirements.txt后续换电脑或重新部署时一条命令就能还原环境pip install -r requirements.txt这既是团队协作的基本要求也是对自己项目的保护。6.3 对生成代码做 Git 版本管理AI 生成的代码同样需要进行版本管理。第一次用 AI 生成完建议立刻执行git init git add mario.py requirements.txt git commit -m feat: 初始版马里奥小游戏后续每次修改、每次 AI 修复 bug都单独提交。这样做的好处是如果某次改动让游戏变差了可以随时回退到上一个可用版本如果 AI 在后续迭代中反复产生新问题也能清晰看出是哪一次改动引入的。6.4 安全与数据边界虽然这次项目只涉及本地游戏代码但还是要提醒一句使用 AI 生成代码时不要把敏感信息写进提示词或代码中比如数据库密码、API Key、内部服务器地址等。AI 生成结果可能存在你没注意到的不安全写法尤其在涉及文件删除、数据库操作、网络请求时必须严格审查后才能在测试环境验证再考虑生产使用。6.5 从“能跑”到“好玩”代码结构演进建议AI 一轮生成的代码通常能跑但结构上比较扁平。如果你想让这个马里奥小游戏继续发展下去建议逐步重构将平台、敌人、旗帜等静态数据抽象成关卡配置。增加sprite组来管理多个敌人和道具。把音频资源、图片资源统一放到assets目录。增加一个settings.py统一管理全局配置。这种演进不是一步到位而是随着需求增多而自然发生。先用极简模式快速拿到能玩的版本再逐步优化是比较推荐的路径。7. 一个可直接复制的实践路径如果你现在就在 Windows 电脑面前想立刻跑通这套流程下面是一份精简行动清单管理员 PowerShell 中执行wsl --install重启。启动 Ubuntu配置用户名密码。创建项目目录并进入。创建虚拟环境并安装 pygame。复制本文第 4 章的mario.py。运行python mario.py。如果窗口弹出并显示游戏画面说明整个链路已经打通。再将第 3 章的极简提示词交给 AI 生成一次代码拿生成结果与示例对照记录差异。最后把这次生成的代码和排错过程整理成笔记。技术成长的路径往往就是这样先用极简方案跑通最小闭环再逐步扩展到多关卡、动画、音效最后才是工程化整理和发布。希望这套“WSL 极简模式 一轮生成”的组合能帮你减少环境折腾的时间把注意力放在真正有趣的地方——写出属于自己的超级马里奥。