简介这是一份基于Linux与Qt框架开发的贪吃蛇游戏完整源码包面向正在学习C和Qt图形界面编程的开发者。代码按模块划分清晰包含界面显示与切换、游戏逻辑控制、等级管理、背景音乐播放、英雄榜分数统计以及帮助功能游戏界面负责绘制蛇和食物并响应键盘操作等级模块根据得分动态改变难度音乐模块支持背景音乐切换英雄榜模块利用数据库保存历史最高分整体涵盖窗口设计、信号槽、事件处理、绘图和本地数据持久化等典型知识点非常适合作为Qt入门后的综合练习。压缩包共七十一个文件包含多份C源码、头文件和界面文件还配有音频与图片素材另有工程文件、编译脚本、资源索引和数据库文件整体大小约十七点二二兆字节部署环境为Linux加Qt 5。包内目录结构完整编译配置齐全可直接构建运行体验完整游戏也能对照代码学习界面布局与模块间通信方法目前已有1473人学习下载。 做过Linux下的图形界面开发又恰好想用一个小项目把Qt的机制串一遍那贪吃蛇确实是绕不开的经典练手题。我前阵子在Ubuntu上从零写了一个完整的贪吃蛇小游戏从窗口搭建到按键控制再到碰撞判定和分数统计整个过程走下来收获比预期大不少。这篇文章就基于Qt Widgets在Linux下的开发实践把整个贪吃蛇的拆解思路、核心代码逻辑、常见坑点一次说透。适合刚接触Qt、想在Linux下做点图形界面小项目的人也适合想复习事件循环、定时器、绘图机制的开发者参考。1. 为什么选择Linux加Qt的组合做贪吃蛇先说结论贪吃蛇这种小游戏用Qt做是最直观的入门路径Linux作为开发环境又能逼着你理解编译链接、Makefile和运行环境的细节不会像Windows那样把很多东西藏起来。很多人会问贪吃蛇不是用C语言加控制台就能写吗何必上Qt。这话没错但控制台版本的蛇和图形界面版本的蛇本质上练的是两个方向的东西。控制台版练的是数据结构——你怎么用链表或数组表示蛇身怎么移动头部、删除尾部而Qt版本额外练的是GUI框架的核心能力——事件循环怎么跑、定时器怎么驱动动画、绘图事件怎么重绘界面、键盘事件怎么响应。这些机制在真实的桌面软件开发里是要天天打交道的比单纯刷算法题实用得多。再说Linux环境。Qt本身是跨平台的但在Linux下写Qt有一个独特的优势你能直接参与从源码到可执行文件的完整流程。qmake或CMake帮你管理构建但底层链接的Qt库、X11或Wayland协议、OpenGL部分驱动这些在Linux都能看得见摸得着。真出了问题排查的路径清晰不会像Windows那样系统帮你做了太多事情反而难以定位。从项目体量来说贪吃蛇控制在几百行代码量级非常适合完整走一遍Qt核心流程。具体来说它能覆盖这些知识点QMainWindow或QWidget窗口体系的搭建QTimer定时器的事件驱动机制绘图事件paintEvent与双缓冲机制键盘事件keyPressEvent的响应处理QPainter绘图API的使用信号与槽的通信方式游戏状态机的简单管理把这些机制走完一遍Qt的骨架基本就立起来了。之后再去做串口助手、图片查看器、上位机界面这类实际项目会发现都是这些基础能力的排列组合。2. 环境准备从安装到第一个窗口跑起来2.1 编译器、Qt库和IDE的选择在Linux下开发Qt需要的东西有三件编译器、Qt开发库、以及编辑器或IDE。三者缺一不可但很多人第一次装Qt的时候会被各种概念绕晕。编译器方面Ubuntu和Debian系系统直接安装g和make即可sudo apt update sudo apt install build-essentialQt开发库是核心包含头文件、动态库和工具链。Ubuntu 22.04和24.04的软件源里都有Qt5不建议直接装最新版Qt6起步因为部分老教程的接口是Qt5的混着看容易乱。sudo apt install qtbase5-dev qt5-qmake qttools5-dev-toolsqtbase5-dev是核心模块包含Qt Widgets、Qt GUI、Qt Core等基础库qt5-qmake提供qmake构建工具qttools5-dev-tools则附带designer等辅助工具。IDE方面Qt官方有Qt Creator功能最全能直接创建工程、调试、看Qt文档。在本机装一个很方便sudo apt install qtcreator如果你和我一样习惯用VSCode加插件的方式也可以只是要自己配置编译任务门槛略高一点。2.2 构建系统的选择qmake还是CMake这是Qt开发里绕不开的问题。初学者直接跟着教程敲qmake是最省力的因为语法简单写进.pro文件里几行就够了。新版Qt6推CMake但Qt5情况下qmake非常成熟而且很多现成例程都是qmake写的照着改不容易出错。我这个项目用的是qmake。一个完整的.pro文件长这样QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET snake_game TEMPLATE app DEFINES QT_DEPRECATED_WARNINGS SOURCES \ main.cpp \ snakewidget.cpp \ snakegame.cpp HEADERS \ snakewidget.h \ snakegame.hTARGET指定生成的可执行文件名TEMPLATE表示生成一个应用程序。SOURCES和HEADERS列清楚源文件和头文件qmake会自动处理依赖关系。有些人对这里的widgets模块有疑问明明前面的QT core gui就够了为什么还要多写一行。因为从Qt5开始Widgets模块从gui中分拆出来了不写进去QWidget、QPainter这些类编译时会直接报找不到头文件。这个坑入门时期几乎必踩这里单独提醒一下。2.3 第一个Qt窗口程序工程建好后先跑一个简单的空白窗口验证环境不要一上来就堆贪吃蛇逻辑。写一个最简单的main.cpp#include QApplication #include QWidget int main(int argc, char *argv[]) { QApplication app(argc, argv); QWidget window; window.setWindowTitle(Snake Game); window.resize(400, 400); window.show(); return app.exec(); }在工程目录下依次执行qmake make如果环境配置没问题终端会编译生成snake_game这个可执行文件运行它就能看到标题为Snake Game的空白窗口。到这里开发环境就算完全打通了。这个验证步骤很关键因为它把编译环境和代码逻辑分开排查。很多人一上来就写几百行代码编译报错时根本分不清是库没装好还是代码写错了。先跑通最小程序后面的开发效率完全不同。3. 贪吃蛇的核心设计数据结构与游戏逻辑3.1 蛇的表示方式贪吃蛇最核心的问题是怎么用代码表示一条会增长、会拐弯的蛇。最直接的思路是用一个点的集合表示蛇身。C标准库里QVector或者QList都能胜任这个角色。每个点用QPoint存储坐标坐标以格子为单位而不是像素。比如界面是20乘20的格子蛇头在坐标(5, 5)食物在(10, 10)蛇身依次是若干连续点。用格子坐标的好处非常明显移动、碰撞判断、绘制全部整数化不会出现浮点数精度问题。同时蛇在每帧的移动就是沿着当前方向走一格逻辑直观QPoint newHead snake.first() directionVector; snake.insert(0, newHead);directionVector根据当前方向决定向右是(1, 0)向左是(-1, 0)向上是(0, -1)向下是(0, 1)。这里有个细节值得单独说为什么要用insert(0, ...)在头部插入新点而不是直接改头部坐标。因为蛇移动的本质是头前进一格尾巴去掉一格。把新头插到最前面然后根据是否吃到食物决定去不去掉尾巴正好是贪吃蛇最标准的移动逻辑。if (ateFood) { // 吃到食物尾巴不动长度加1 } else { snake.removeLast(); // 没吃到食物尾巴去掉 }用链表还是数组在这个场景下区别不大但QVector的随机访问能力在绘制代码里会更方便比如遍历蛇身每个点画方块时用下标访问比迭代器更直观。3.2 方向控制与非法转向贪吃蛇有一个经典的逻辑陷阱蛇头正在向左走的时候你不能直接让它向右掉头因为那样蛇头会直接撞到紧跟着的身体。同理向上走时不能直接向下。处理方式是在设置方向的函数里加一层判断void SnakeGame::setDirection(SnakeGame::Direction newDir) { if ((currentDir Left newDir Right) || (currentDir Right newDir Left) || (currentDir Up newDir Down) || (currentDir Down newDir Up)) { return; // 非法转向直接忽略 } currentDir newDir; }这个判断必须在按键事件里做不能在定时器触发移动时才做。如果放在移动时判断会出现一帧内连按两个方向键导致蛇瞬间反向的bug。具体来说如果蛇正在向左走你快速按下上、右两个键实际存储的方向先变成上再变成右。如果定时器此时才触发它看到的当前方向是右而右和左是反向的碰撞就发生了。所以在设置时拦截非法转向比在移动时判断要可靠得多。3.3 坐标边界与碰撞判定碰撞判定的范围有几种不同处理方式。最常见的是撞墙必死——蛇头超出地图边界游戏结束。另一种是穿墙——从左边出去就进到右边像贪吃蛇大作战那样。两种都行但实现时的边界条件要写清楚。撞墙模式bool hitWall head.x() 0 || head.x() GRID_WIDTH || head.y() 0 || head.y() GRID_HEIGHT;穿墙模式则是做一个取模运算int wrappedX (head.x() GRID_WIDTH) % GRID_WIDTH; int wrappedY (head.y() GRID_HEIGHT) % GRID_HEIGHT;我个人推荐新手先做撞墙模式因为逻辑更朴素也方便你验证边界点。稍微留意一下判断撞墙要在蛇移动之后立刻做因为新头的坐标一旦越界后续绘制和身体碰撞判断就全都不可信了。还有自碰判定。蛇头碰到自己身体的任意一节游戏结束。这个判断用QVector的contains方法最简单但需要排除特殊情况bool hitSelf snake.indexOf(head, 1) ! -1;indexOf的第二个参数表示从下标1开始查找。为什么要从这个位置开始因为蛇头本身永远是snake.first()从0开始查找的话必然能找到头自己。从1开始就是排除头自身只检查身体。3.4 食物生成与吃到食物的判定食物生成的核心要求是随机且不与蛇身重合。随机数在Qt里用QRandomGenerator即可比C标准库的mt19937使用起来更简单int randX QRandomGenerator::global()-bounded(GRID_WIDTH); int randY QRandomGenerator::global()-bounded(GRID_HEIGHT); QPoint food(randX, randY);生成后要检查食物是否落在蛇身上。如果重合就重新生成。这里有趣的边界情况是当蛇几乎铺满整个地图时生成一个不在蛇身上的食物会变得很困难甚至可能死循环。最简单的处理是设置一个尝试次数上限比如最多生成500次如果都重合就认为地图已满直接判定胜利。绝大多数情况下不会触发这个分支但写上这个保护能避免潜在的死循环隐患。吃到食物的判定很简单新头坐标等于食物坐标就说明吃到了。bool ateFood (snake.first() food);吃到了就把食物标记为已吃掉下一帧或当前帧末尾重新生成新食物同时分数加一。注意不要在吃到食物的瞬间立刻生成新食物因为此时蛇头还在食物坐标上如果新食物恰好生成到蛇头附近视觉上会显得很怪。正确的节奏是先完成这一帧的蛇生长不删除尾部然后再重新生成食物。3.5 分数与游戏状态管理分数采用一个简单规则每吃到一个食物加10分。这个数值在游戏里以文本形式显示在界面上。游戏状态用一个枚举管理逻辑清晰enum GameState { Ready, // 未开始 Running, // 运行中 Paused, // 暂停 GameOver // 结束 };状态机的意义在于拒绝非法操作。比如游戏中按空格应该是暂停暂停时按方向键不能改方向游戏结束后按确定可以重新开始。如果不引入状态管理直接用一堆bool变量代码写到后面会发现各种组合条件根本理不清。4. Qt界面绘图QPainter与窗口控件的搭建4.1 自定义Widget还是用QLabel贪吃蛇的绘制有两种实现路线。一种是用QLabel放像素图每次更新时生成新图片另一种是自定义QWidget子类重写paintEvent用QPainter直接画。多数Qt项目都会选后者因为QPainter的绘图方式更直接性能也足够应对贪吃蛇这种简单画面。这里需要解释一下所谓直接画的含义。QPainter提供了一系列绘图API比如drawRect可以画矩形drawText可以画文字。在paintEvent里调用这些API图形会绘制到当前窗口的光栅缓冲区上然后由Qt框架统一刷新到屏幕。界面搭建上我直接用一个QWidget作为游戏空白。为了把游戏区域和分数区域区分开我在SnakeWidget的顶部用布局管理器放置了一个QLabel用于显示分数下方是游戏画布。SnakeWidget::SnakeWidget(QWidget *parent) : QWidget(parent) { game new SnakeGame(GRID_WIDTH, GRID_HEIGHT); scoreLabel new QLabel(Score: 0, this); scoreLabel-setAlignment(Qt::AlignCenter); QVBoxLayout *layout new QVBoxLayout(this); layout-addWidget(scoreLabel); layout-addWidget(game); connect(game, SnakeGame::scoreChanged, this, SnakeWidget::updateScore); }这里的关键连接是scoreChanged信号。游戏分数变化时SnakeGame发出信号SnakeWidget里的updateScore槽函数接收并更新label。这种设计符合Qt的架构规范——游戏逻辑与界面显示之间通过信号解耦而不是在游戏类内部直接操作UI控件。4.2 paintEvent里画格子线、蛇和食物绘制是贪吃蛇最看得见的部分也是QPainter绘图机制的核心实践。我用的GRID_SIZE是20像素即一个格子占20乘20像素。地图是20乘20的格子所以整个窗口大小为400乘400像素。绘制代码分为三个部分背景、蛇身、食物。背景用浅灰色填充整个窗口再用细线画出格子线这样蛇移动的轨迹会清晰可见。void SnakeGame::paintEvent(QPaintEvent *) { QPainter painter(this); painter.fillRect(rect(), QColor(40, 40, 40)); // 画网格 painter.setPen(QPen(QColor(60, 60, 60), 1)); for (int x 0; x GRID_WIDTH; x) { for (int y 0; y GRID_HEIGHT; y) { painter.drawRect(x * GRID_SIZE, y * GRID_SIZE, GRID_SIZE, GRID_SIZE); } } // 画蛇 painter.setBrush(QBrush(QColor(0, 200, 0))); painter.setPen(Qt::NoPen); for (const QPoint p : snake) { painter.drawRect(p.x() * GRID_SIZE, p.y() * GRID_SIZE, GRID_SIZE, GRID_SIZE); } // 画食物 painter.setBrush(QBrush(QColor(255, 0, 0))); painter.drawEllipse(food.x() * GRID_SIZE, food.y() * GRID_SIZE, GRID_SIZE, GRID_SIZE); }绘制中有两个容易忽略的细节。第一个是每帧绘制前应该把整个窗口清掉否则上一帧残留的内容会和这一帧叠加在一起造成视觉残影。这里用fillRect(rect(), QColor(...))做了全局填充相当于手动清屏。第二个是绘制效率问题。你可能注意到每帧都画了一遍全部的网格线这在400乘400的小窗口上毫无压力。但如果你把地图扩大到100乘100甚至更大这种O(N平方)的绘制方式就会带来明显的性能问题。到那时可以用QOpenGLWidget或者预绘制网格线到离屏QPixmap来优化。贪吃蛇这个规模不需要考虑这些但你得知道存在这个演进方向。4.3 键盘事件与焦点问题键盘事件是交互的核心。在SnakeGame中重写keyPressEventvoid SnakeGame::keyPressEvent(QKeyEvent *event) { switch (event-key()) { case Qt::Key_Up: game-setDirection(SnakeGame::Up); break; case Qt::Key_Down: game-setDirection(SnakeGame::Down); break; case Qt::Key_Left: game-setDirection(SnakeGame::Left); break; case Qt::Key_Right: game-setDirection(SnakeGame::Right); break; case Qt::Key_Space: game-togglePause(); break; case Qt::Key_Return: case Qt::Key_Enter: if (game-isGameOver() || game-isReady()) game-start(); break; default: QWidget::keyPressEvent(event); break; } }焦点问题是一个典型的新手坑键盘事件只会发给当前拥有焦点的控件。如果你的窗口上有一个按钮或者文本框焦点可能不在SnakeGame上按方向键根本不会触发任何反应。解决方式有两种要么在构造函数里设置this-setFocusPolicy(Qt::StrongFocus)确保Widget能抢到焦点要么在MousePressEvent里点击窗口时强制设置焦点。最稳妥的是两个都做同时要在游戏进行时确保焦点不被其他控件夺走。5. QTimer事件驱动机制让蛇自己动起来5.1 定时器驱动蛇的移动静态的蛇不算游戏蛇要自己动才行。这就牵扯到Qt最核心的机制之一——事件循环。Qt程序执行app.exec()后进入事件循环它不停地在等待各种事件鼠标事件、键盘事件、定时器事件、网络事件、绘制事件等等。QTimer的本质就是每隔固定时间向事件循环发送一个定时器事件触发对应的槽函数。在游戏里我这里用了一个QTimer来控制移动频率。把它设置为每150毫秒触发一次moveSnake()槽函数。speedTimer new QTimer(this); speedTimer-setInterval(150); connect(speedTimer, QTimer::timeout, this, SnakeGame::advance);移动的频率直接决定游戏难度。150毫秒是比较舒服的入门速度随着分数提升可以逐步加快到100毫秒、80毫秒。加快的方式就是改变setInterval的数值Qt的定时器会动态调整触发频率。有个细节值得注意定时器事件触发时代码是单线程执行的。这意味着moveSnake()执行期间键盘事件和绘制事件都会被阻塞。所以moveSnake()里不能做耗时操作否则蛇会变得一卡一卡的。如果将来你要加音效、动画特效这些东西得另想办法但贪吃蛇的移动逻辑本身不耗时用单线程完全够用。5.2 start、pause与restart的状态切换游戏状态管理在定时器的启停上体现得非常直接。start()启动定时器暂停时停止定时器游戏结束时也停止定时器重新开始时再启动。void SnakeGame::start() { snake.clear(); snake QPoint(GRID_WIDTH / 2, GRID_HEIGHT / 2); snake QPoint(GRID_WIDTH / 2 - 1, GRID_HEIGHT / 2); snake QPoint(GRID_WIDTH / 2 - 2, GRID_HEIGHT / 2); currentDir Right; nextDir Right; score 0; emit scoreChanged(score); generateFood(); setGameState(Running); speedTimer-start(); update(); }这串初始化代码能看出蛇的初始状态蛇头在地图中心蛇身向右延伸两节初始方向向右。这个初始布局不是随便定的——中心位置的蛇不会在游戏开始第一帧就撞墙向右的方向也和蛇身朝向保持一致不会出现初始倒转的bug。pause逻辑更简单void SnakeGame::togglePause() { if (state Running) { state Paused; speedTimer-stop(); } else if (state Paused) { state Running; speedTimer-start(); } }暂停的本质就是停止定时器让蛇停在当前画面。这时如果用户在暂停状态下按方向键setDirection处理里应该判断状态不是Running就直接返回。这种细节看起来小但往往是游戏手感好坏的分水岭。5.3 定时器间隔与游戏速度的进阶控制一个小的进阶玩法是每吃5个食物就提高一次速度。实现方式是在advance()里检测分数的变化达到阈值就减少定时器的间隔if (speedTimer-interval() 50) { speedTimer-setInterval(speedTimer-interval() - 10); }不过这么做有个副作用速度变化太突然的话玩家会感觉一下子失控。更稳的方案是线性递减比如每吃一个食物减少2到3毫秒。我实测下来150毫秒起步、每吃一个食物减少2毫秒是一个比较平滑的曲线玩家能有明确的啊越来越快了的感受但不至于一上来就手忙脚乱。6. 踩坑记录Linux下Qt开发贪吃蛇遇到的典型问题6.1 编译链接错误Qt库版本混乱Qt5和Qt6混装是Linux下最常见的坑。如果你的系统里通过apt装了Qt5又手动装过Qt6的离线包qmake和make的时候很可能引用版本不匹配的库。典型报错是类似/usr/bin/ld: cannot find -lQt5Widgets或者运行时提示找不到Qt5库This application failed to start because no Qt platform plugin could be initialized.这个报错看上去像是插件问题但根因往往是系统里多个Qt版本共存qmake找到的库和编译时指定的头文件不是一套。排查方法就是确定当前qmake的版本并确保PATH指向你期望的那一个which qmake qmake --version ldd ./snake_game | grep QtWindows上遇到的no qt platform plugin could be initialized在Linux下很少见但如果你的环境变量里有乱七八糟的QT_PLUGIN_PATH指向别的Qt版本目录同样会出现这个报错。解决办法就是移除或修正这个环境变量。6.2 键盘事件无响应这个坑出现的概率极高。我在前面提到过焦点问题但还有一个可能的原因是keyPressEvent的参数类型不对。Qt的键盘事件接收函数必须严格写成void keyPressEvent(QKeyEvent *event) override;如果你写成了其它参数类型或者少了override关键字编译可能不报错但你的函数永远不会被你重写的那一个调用。因为基类QWidget的keyPressEvent是虚函数你定义的同名函数如果参数不匹配就只是隐藏了父类函数虚函数机制完全不会介入。这个bug非常隐蔽检查时一定要留意函数签名。6.3 窗口尺寸与绘制区域不匹配如果窗口的resize尺寸和格子坐标对不上会出现游戏区域显示不全或超出窗口的视觉问题。记得我在代码里用的是固定400乘400的窗口配合GRID_WIDTH乘GRID_SIZE的逻辑一定要保证resize(GRID_WIDTH * GRID_SIZE, GRID_HEIGHT * GRID_SIZE);如果忘了做这个换算直接resize(400, 400)但网格定义是30乘30乘20像素最后画出来的蛇和食物会超出窗口可见区域。经验是把地图尺寸、格子大小、窗口尺寸的换算写成一个常量表达式这样改一个数值时不会忘了另一个。6.4 绘图闪烁问题Qt的paintEvent默认情况下已经做了双缓冲所以一般的贪吃蛇游戏不会出现明显的闪烁。但如果你在paintEvent里反复调用update()或者在定时器槽函数里做了复杂的绘制操作闪烁就会冒出来。我这个项目没遇到闪烁因为绘制逻辑简单但我在开发过程中试过一次在槽函数里直接获取painter绘制结果画面撕裂。正确做法是把绘制逻辑全部放进paintEvent槽函数里只是修改游戏数据然后调用update()请求立即重绘。Qt会在合适的时间统一处理这个重绘请求这是最稳妥的。7. 完整运行效果与可扩展的优化思路程序编译运行后窗口顶部的分数标签会显示Score: 0黑色背景的网格区域里一条绿色的蛇停在地图中央等待操作。按任意方向键游戏立即开始蛇按固定节奏移动。每吃到一个红色圆形食物分数增加10分蛇身增长一格食物重新随机生成。按空格暂停和继续游戏结束后按回车重新开始。整体效果属于朴实但完整的类型基础功能全部都实现了而这也正是一个好项目的状态——可以在此基础上按自己兴趣加功能。如果你想让这个项目更有挑战性我推荐以下几个扩展方向第一加入障碍物。在地图内随机生成若干不可穿越的障碍格蛇碰到即死亡。这会引入寻路问题因为食物可能生成在障碍物包围的封闭区域需要额外处理。第二加入AI自动寻路。让蛇自己找食物。这个方向比较硬核涉及经典的Hamiltonian cycle或者广度优先搜索策略。能写一个在20乘20地图里长期不死的小蛇是算法功底的绝佳展示。第三加入音效和视觉效果。吃食物时播放一个短音效蛇身颜色从绿到蓝渐变食物做呼吸动画效果。主要练的是Qt的资源管理、QMediaPlayer的使用和定时器驱动的动画技巧。第四把游戏数据持久化。把最高分保存到本地配置文件启动时读取。Linux下这个路径一般是$HOME/.config/YourAppName/config.iniQt的QSettings类可以几行代码搞定。贪吃蛇这个项目确实是那种写完觉得没什么回头再看学到很多的典型。它工程量不大但走通的是Qt应用从创建到运行的完整链路。我在后来做实际项目时事件循环、绘图、信号槽这些基础概念能立刻衔接上手都得归功于当初把这个小项目写得够完整、坑踩得够多。本文还有配套的精品资源点击获取