简介：一款基于Cocos2D-X引擎的手游麻将完整源码，面向对麻将玩法实现与跨平台2D游戏开发感兴趣的开发者，可用于学习商业休闲游戏的项目组织方式。资源共584个文件，压缩包约16.22MB，包含212个ogg音频文件、126个png图片素材、64个cpp与72个h源码文件，以及Android相关java文件、xml/plist配置和数据库文件，覆盖了代码、资源、配置与数据存储各层面；代码结构上涵盖桌面逻辑、机器人模拟、公共函数等模块。已有2530人学习下载。源码中可重点研究Cocos2D-X的场景、精灵、动作系统，麻将洗牌、出牌、胡牌判定的核心算法，以及UI交互、网络通信、数据存储和多平台适配的实现方式。整体按模块划分，文件类型多样，适合作为游戏开发进阶的实战参考与代码研读资料。

1. 先说清楚：标题里的“手游欢乐麻将源码”到底指什么

很多开发者拿到一个写着“手游欢乐麻将源码”的压缩包，第一反应是解压后双击、编译、跑起来就能进游戏。实际上一套能称得上“源码”的棋牌手游项目，从来不是一个单机工程，而是由客户端、服务端、数据库、运营后台组成的完整系统。你看到的标题，通常指这类仿某热门欢乐麻将玩法的开源或半开源棋牌项目源码，用于学习技术、做二次开发、搭一套自用测试环境。

它能解决的核心问题有三个：一是让你看到棋牌手游从登录到进房、从发牌到结算的完整链路；二是给你一套可以改玩法、改界面、改成自己产品的代码基础；三是帮助你理解服务端如何在低延迟场景下维持多房间并发。它适合移动端开发者和游戏后端工程师，也适合想从零搭一套棋牌游戏原型来验证想法的人。

但它不是解压即玩、点开即上线的成品。源码里往往缺资源、缺密钥、缺平台配置，甚至缺关键模块的授权。把这个标题理解成“一套可以研究、可以改造、需要自己搭环境的工程”，比理解成“现成的游戏”要准确得多。接下来我按实际动手的顺序，把这个标题背后的东西拆开讲。

2. 拿到源码先别急着跑：先拆目录，把工程结构搞明白

2.1 一套典型棋牌手游源码的目录长什么样

我见过的这一类源码，不管打包成什么名字，内部结构大体一致。先把根目录列出来，你会看到几个固定角色：

先别急着进任何一个目录。第一步是看根目录有没有 README 和“版本说明.txt”这类文件。很多源码作者会把运行环境的依赖版本、启动顺序、默认端口写在里面。如果 README 缺失，就按目录名和配置文件反推，但这就进入玄学阶段了，后面会踩不少坑。

我一般会先用一条命令把整个工程的目录树输出到文件里，然后根据目录命名判断模块边界。这样做的意义不是好看，而是确认一件事：客户端和服务端的通信协议是自研的还是用了现成框架。协议决定你后面看代码时的主线路。

2.2 先看服务端还是先看客户端：我的判断顺序

很多新手拿到源码，第一反应是先把 Unity 或 Cocos 工程打开。这个习惯在棋牌源码上会浪费大量时间。原因是客户端工程通常带着完整的第三方 SDK、渠道包配置、资源目录，光是导入工程、解决依赖就要半小时。而且客户端编译出来的东西，没有服务端配合也跑不出完整玩法。

我的顺序是：先看服务端能不能启动，再看数据库脚本能不能执行，最后才碰客户端。服务端是棋牌项目的根，登录、房间、发牌、结账全在服务端，客户端只是把服务端算好的结果展示出来。服务端一旦跑通，你就有了一个“黑匣子”，可以用它验客户端的连接是否正确。

还有一个更实际的原因：绝大多数棋牌源码的服务端依赖项比客户端少得多。一个 JDK、一个 MySQL、一个 Redis 就能起服务。而客户端要装编辑器、打包工具、安卓 SDK，开发机和测试机来回折腾。先用最小代价验证系统是活的，再一步步加东西，这套思路在源码研究里永远适用。

2.3 搭建依赖环境：先凑齐一套保守的组合

不要一上来就装最新版的 JDK、MySQL，因为棋牌源码的服役时间往往比较早，新版本反而会引入兼容性报错。我常用的保守组合是：JDK 8、MySQL 5.7、Redis 6.x、Nginx 1.20 左右。这个组合能覆盖大多数 Java 系棋牌服务端，如果是 Go 或 Node.js 写的，就按对应语言版本调整，Go 1.18 以上、Node.js 14 以上基本够用。

检查环境的命令如下，先确认机器上已经有这些工具：

java -version mysql --version redis-server --version node -v 2>/dev/null; go version 2>/dev/null

这段命令看的是基础环境。java -version确认 JDK 版本，mysql --version和redis-server --version确认数据库与缓存，后面两行是兼容性检查，输出为空说明本机没装对应运行时。参数2>/dev/null的作用是屏蔽掉“命令不存在”的报错，让输出更干净。

如果缺其中某项，先装齐再继续。MySQL 安装后要确认能本地登录，Redis 不用做密码认证的话默认监听 6379 即可。这一步看着简单，但很多翻车现场都出在这：JDK 版本太高导致 Netty 启动异常，MySQL 8 的认证插件和源码里的旧驱动不匹配，Redis 没装导致登录时 token 写不进去。

2.4 配置文件里先找出这几样东西

服务端能启动之前，必须把硬编码在配置文件里的地址、密码、密钥找出来。棋牌源码的配置文件通常叫 application.properties、config.yml、db.properties，散落在 server 工程的不同模块下。用下面这组命令先把可疑字段揪出来：

grep -rn "jdbc:mysql" --include="*.properties" --include="*.yml" --include="*.xml" server/ grep -rn "redis" --include="*.properties" --include="*.yml" --include="*.xml" server/ grep -rn "privateKey\|secret\|password" --include="*.properties" --include="*.yml" server/

第一条命令找数据库连接串，第二条找 Redis 配置，第三条找密钥和明文密码。这三个字段是跑通服务端的命门。连接串里的 IP、端口、库名、账号密码，必须改成你自己环境的实际值。很多源码自带配置写的是127.0.0.1和空密码，但库里压根没有初始化数据，这就要和 database 目录里的脚本配合处理。

改配置时注意一个细节：不要把端口改乱。服务端所有对外端口、对内端口，都可能在别的模块里被引用。改一个端口之前，先全局搜一下有没有其他地方引用同一个端口号。在这个阶段，尽量保持默认端口，只改数据库和 Redis 的访问信息，能少一半的排错工作量。

3. 服务端：让房间游戏逻辑跑起来的关键

3.1 服务端模块划分：网关、房间服、玩牌服不是一回事

一个能撑住多人对战的棋牌服务端，绝不是一个单进程程序。我拆过的源码里，常见的是三层结构：网关层、逻辑层、数据层。网关层负责维持客户端长连接、做消息转发、鉴权；逻辑层里面又拆成房间管理和玩法计算；数据层跑 MySQL 和 Redis，存账号、房卡、对局记录。

用表格看更清楚：

切分模块的目的很直接：网关层出问题只影响连接，不影响已经开始的牌局；玩牌服出问题只影响本房间，不至于把大厅拖垮。源码里如果只有一个 Java 进程包含所有逻辑，那是给学习和测试用的简化版，上线级项目基本都拆开了。

从排查角度讲，这个结构告诉你一个原则：客户端报错时，先分清是哪一层的问题。连不上服务器先查网关，登录失败先查大厅和数据库，进房失败先查房间服。不然你会陷在客户端代码里瞎翻半天。

3.2 从数据库初始化到一键启动：最小可运行命令

跑通服务端的起点是数据库。源码里的 database 目录下的 SQL 脚本，通常要按特定顺序执行，先建库，再建表，再插入配置数据。很多源码坑就在这里：脚本里有外键依赖，顺序反了直接报错。

我习惯先看脚本文件名里的编号，比如001_create_db.sql、002_create_table.sql、003_init_data.sql。执行方式用 mysql 命令行最简单：

mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS mahjong DEFAULT CHARSET utf8mb4;" mysql -uroot -p mahjong < database/001_create_db.sql mysql -uroot -p mahjong < database/002_create_table.sql mysql -uroot -p mahjong < database/003_init_data.sql

第一条命令是建库，utf8mb4是为了能存玩家昵称里的特殊字符。后面三条是依次导入结构、导入核心表、导入初始配置。<符号表示把文件内容作为 SQL 输入，比在客户端里手动复制要稳得多。执行完没有任何报错，才算数据库这关过了。

接着启动服务端。Java 系的服务端通常是一个 jar 包和启动脚本，常见做法是后台运行加日志输出：

cd server/bin nohup java -jar mahjong-server.jar --spring.config.location=../config/application.properties > ../logs/server.log 2>&1 &

nohup让进程在断开 SSH 后继续运行，> ../logs/server.log把输出写进日志文件，2>&1把错误输出也合并到同一个文件里。启动后别急着连客户端，先看日志里有没有started或listen on 0.0.0.0:9000这类关键行。如果有报错，直接去日志文件里搜Exception，比问任何人都有用。

启动完服务端，再用 redis-cli 检查 Redis 里有没有写入令牌或缓存。如果 Redis 一直是空的，大概率是服务端连 Redis 失败，或者配置项没生效。

3.3 房卡模式与金币场的实现差异

棋牌源码里最核心的两套玩法模式是房卡模式和金币场模式。房卡模式又叫亲友圈，玩家创建房间，消耗房卡，然后拉好友进来玩，打完一局结算，房间解散。金币场则是玩家进入一个大的匹配池，系统自动撮合四人开局，赢了获得虚拟金币。

这两套模式在源码里是两套完全不同的数据流。房卡模式的核心是“房间”和“房卡余额”，数据结构偏重订单：谁开的房、扣了谁多少卡、房间号是多少。金币场核心是“匹配池”和“竞技值”，数据结构偏重队列：谁在等、匹配区间是什么、胜率影响因子是什么。

典型表结构对比如下：

改源码时这两个模式别混着改。我见过有人把金币场的结算逻辑搬到房卡模式里，结果每局结束所有玩家的金币都被扣了一遍。房卡模式里没有“金币池”这个概念，结算要看订单表；金币场里没有“房卡”这个概念，结算要看流水表。先分清楚，再动手改。

3.4 机器人对手是怎么实现的：这不是你想象的机器学习

棋牌源码里经常带一个“机器人”或“AI玩家”模块。它的作用不是像图像识别那样用模型推理，而是用一套规则引擎模拟真实玩家行为。常见实现是：机器人进入房间，根据手牌做“听牌判断”“拆搭子”“跟打熟张”，再由一个难度参数决定出错的概率。

下面这段伪代码能说明核心逻辑：

def choose_discard(hand_tiles, last_discard, difficulty=0.5): # 1. 先看有没有安全牌（别人刚刚打过的牌） safe_tiles = [t for t in hand_tiles if t == last_discard] if safe_tiles and random.random() < difficulty: return safe_tiles[0] # 2. 再按胡牌概率给手牌排序 hand_tiles.sort(key=lambda t: win_rate(hand_tiles - {t})) # 3. 按难度决定是否打最差的牌 if random.random() < difficulty: return hand_tiles[-1] return hand_tiles[random.randint(0, len(hand_tiles) - 1)]

这段逻辑的关键是难度参数difficulty：机器人不是每手都打最优牌，而是按概率出错。初级机器人difficulty设 0.3，高级机器人设 0.9，玩家的体感差别就出来了。注意这里用的是random.random()做随机决策，真正上线时要用安全随机数，否则玩家能通过已知随机种子反向算出牌序。

理解机器人实现的好处是，当你二次开发时不用去改客户端逻辑，只需要调服务端里机器人的难度参数、出牌策略权重，就能改变游戏难度。这个模块也是防外挂检测的天然样本库：服务端知道机器人会怎么出牌，如果玩家出牌风格和机器人高度重合，就有疑似脚本嫌疑。

4. 客户端：从资源加载到登录进房，抓住三条链路

4.1 客户端网络层：先认准连接、心跳、消息号

客户端是一套独立的工程，但它所有玩法都依赖和服务端的通信。看客户端代码时，不要一头扎进 UI 界面，先找网络层。网络层一般封装在NetworkManager或SocketClient类型的类里，核心就三件事：建立连接、发送心跳、派发消息号。

典型的心跳逻辑长这样：

void SendHeartbeat() { // 心跳消息：每20秒发送一个空包，保持连接不超时 Message msg = new Message(); msg.msgId = 10001; // 10001 是心跳消息号，与服务端约定 msg.body = "{}"; socket.Send(msg); }

这段代码的msgId是客户端和服务端之间的“暗号”。10001 在服务端对应一个onHeartBeat处理器，客户端发的每一条消息都要带这个编号。新手最容易翻车的地方是改客户端代码时，把消息号写错了，服务端收到后直接当成未知消息丢弃，表面现象就是“点了按钮没反应”。

网络层里还有一个重点：数据包粘包和拆包。棋牌项目属于高频小包通信，一局出牌几十次，TCP 粘包几乎必然发生。源码里一般会定义包头结构，前 4 字节是长度、后面才是正文。看网络层时先确认有没有按长度拆包，如果没有，加消息时很容易导致协议解析错位，整个房间数据错乱。

4.2 登录流程：账号、token、服务器列表

客户端的登录链路值得完整跟一遍，因为它是连接大厅和房间入口。通常流程是：客户端先向 HTTP 接口提交账号密码，拿到 token 和服务器列表，再用 token 去连接网关服务器。

我一般先看登录相关的类：

public async void Login(string account, string password) { // 第一步：向 auth 服务请求登录令牌 var token = await http.Post("/auth/login", new { account, password }); // 第二步：拿令牌请求服务器列表 var serverList = await http.Get("/server/list", token); // 第三步：选择第一个可用的游戏服务器，建立长连接 socket.Connect(serverList[0].ip, serverList[0].port); socket.Send(new Message(10002, token)); // 10002 = 登录消息号 }

这里的三个步骤是层层递进的：第一步拿token，第二步拿serverList，第三步才是真正的游戏长连接。源码里如果写死了服务器 IP，那说明是针对单一服务器设计的；如果serverList来自 HTTP 响应，说明支持多区服负载。

排查登录问题时要盯住这个链路：账号密码对不对看第一步，服务器列表为空看第二步，连接后立刻断开看第三步。很多源码登录失败不是密码错，而是服务端没给 token，HTTP 接口返回的已经不是 200，客户端还在傻等。

4.3 资源热更与分包：源码里一般怎么处理

棋牌源码和单机游戏源码的最大区别就是热更。同一个 client 目录下，往往有assets和update两个资源目录。assets是打包进安装包的，update是放在服务器上用版本号控制下载的。源码自带的资源通常是占位图和低精度模型，真正的美术资源本来就不全，这也是源码打出来包很大的常见原因。

看热更逻辑时关注版本号对比：

// 客户端启动时请求远程版本 const remoteVersion = await http.get('/version/check', { localVersion: Game.version }); if (remoteVersion > Game.version) { const urls = await http.get('/version/diff', { from: Game.version, to: remoteVersion }); await downloadAndReplace(urls); // 下载差异资源并覆盖本地缓存 Game.version = remoteVersion; }

这里的核心是“差异资源”。客户端只更新变化部分，而不是下载整个安装包，这是棋牌项目更新效率的命门。你在源码里看到的version参数，一定要维护好：改了一点 UI 资源，就把版本号加一，否则玩家端永远显示旧界面。

热更目录还有个坑，就是本地缓存覆盖逻辑。如果改完资源后没有清掉本地缓存，客户端会一直读取旧文件，表现就是“代码明明改了，跑起来还是老样子”。清 Cache 是热更调试里的首要动作。

4.4 打包上真机：Android 与 iOS 的差别

客户端最终要装到手机上才有意义。Android 打包相对直接，用 Android Studio 或 Unity 的导出功能生成 APK，签名用 debug keystore 也能跑。难点在渠道包：源码里常见的channelID、PlatformAdapter类，就是为了让同一个 APK 能在不同应用商店上报不同数据。

iOS 打包麻烦一点。棋牌源码里如果写了苹果的登录授权和防沉迷逻辑，你需要有自己的开发者证书，还要配置推送证书。没有证书时，源码里的支付、推送、登录授权模块都会编译报错。我的建议是：研究阶段只打 Android 包，把 iOS 相关代码用宏屏蔽掉，省下的时间够你把对局逻辑多读两遍。

另外，真机调试时最让人头疼的是崩溃日志。源码自带的 bugly 或友盟统计如果开了，崩溃会直接看云端后台；如果没开，就只能靠 Android 的 logcat 抓日志。抓日志的时候先过滤GameCore和SocketClient等网络相关标签，很多时候崩溃是空指针，不是网络问题。

5. 避坑：这套源码里最常见的六个翻车现场

5.1 源码压缩包自带后门和木马

现象：服务端刚启动，服务器 CPU 突然飙高，或者外网 IP 被不断扫描攻击。

原因：很多流传的棋牌源码在打包时会被植入后门脚本，常见位置是启动脚本里多一行curl下载命令，或者在某个 Java 类里藏了反弹 shell 的逻辑。这类源码来自灰色渠道，作者可能故意留后门，也可能在传播过程中被别人二次污染。

解决：拿到源码第一件事，不要直接启动，先全盘搜索危险接口。我习惯搜这几类关键词：Runtime.getRuntime().exec、ProcessBuilder、curl、wget、/bin/sh。搜到后看上下文，如果在启动脚本里，直接删掉；如果在业务代码里，要看是不是被动态调用。排查完后再配防火墙，只放行数据库和游戏端口，管理后台别暴露到公网。

5.2 数据库脚本执行顺序不对，全是表不存在

现象：启动服务端后，日志一直报Table 'mahjong.player' doesn't exist，或者登录接口报数据库异常。

原因：源码里的 SQL 脚本不是按文件名顺序排列的，有的是先插配置数据后建表，有的是两个脚本有依赖关系。用工具一键导入时，导入工具按文件名排序执行，结果配置表还没建好就开始插数据。

解决：不要信任脚本文件名顺序，先打开每个脚本文件看第一行是CREATE TABLE还是INSERT INTO。按“建库、建表、索引、配置数据、初始化数据”的顺序手工排列执行。如果报错，把 MySQL 的错误码记下来，看是外键问题还是字段重复问题，再微调。

5.3 Redis 缓存没清，登录永远提示用户不存在

现象：服务端能启动、账号能注册，但用刚注册的账号登录就报“用户不存在”。

原因：登录鉴权时会先查 Redis 缓存，再查 MySQL。数据库已经写了新用户，但 Redis 里的用户缓存还是旧的，或者注册服务没把新用户同步写入 Redis，导致查询走了错误的数据源。

解决：先执行redis-cli flushall清掉所有缓存，再重新登录。如果还有问题，就去看注册接口的代码，确认注册成功后有没有调用 Redis 写入的语句。这是典型的“数据库有数据、客户端看不见”的坑，先查缓存再查库，顺序不能反过来。

5.4 客户端连不上服务端：IP、端口、协议三处对不上

现象：客户端点击登录，转圈几秒后提示“网络异常”，但服务端日志没有任何连接记录。

原因：客户端连接的不是服务端监听端口。可能原因有三个：客户端配置写的是 127.0.0.1，但手机和服务端不在同一网络；端口号被占用，服务端实际监听的是其他端口；协议类型不匹配，服务端是 TCP，客户端按 WebSocket 发的。

解决：先用netstat -tunlp | grep java看服务端实际监听的端口。然后在电脑上先用telnet 服务器IP 端口测试通不通，通了再连手机。最后确认客户端配置里的协议类型：TCP 还是 WebSocket 还是 HTTP 轮询，这几样完全不兼容。调试时建议让客户端日志输出服务端返回的原始报文，能看到字节数是 0 还是要到的数据不对。

5.5 牌局结果对不上账：时间戳与随机种子的坑

现象：两个客户端看到的同一局手牌不一样，或者结算时金币数和服务端记录不一致。

原因：棋牌项目是服务端权威计算，客户端只展示结果。如果客户端也参与了发牌计算，或者服务端用了可预测的随机种子，就会出现不同步。另一个常见原因是服务器时间不准，玩家在某个时间点前的对局被记成另一天，导致结算报表错乱。

解决：源码里凡是用Math.random()的地方，都要改成安全随机数生成器。对局记录以服务端时间为准，部署时统一用 NTP 同步服务器时间。客户端判断是否和服务端同步时，不要用两个客户端的时间差值，要用服务端下发的对局时间戳。

5.6 “试玩模式”和“正式模式”不是一个开关

现象：按源码文档配置好“正式模式”，但房间人数上限、初始金币还是和试玩时一样。

原因：源码通常用一个GameMode常量控制试玩和正式逻辑，但很多人在配置文件里改的是另一个debug开关，真正的模式枚举写在编译常量里，改配置不生效。

解决：全局搜索GameMode或isTest，找到赋值的地方，区分编译常量和运行配置。试玩模式会跳过支付鉴权、缩短对局时间、把机器人难度调低，真正上线时必须确认这几个逻辑都切到正式分支。这个坑最隐蔽，因为它不报错，只是行为不对。

6. 从源码到你能自己做的东西：验证与二次开发

把服务端和客户端都跑通之后，只说明工程能启动，不代表它能成为你的产品。这段时间我最常做的一件事，是定义“最小闭环”：注册账号、登录大厅、创建房间、拉满四个机器人、打一圈牌、完成结算。这个闭环跑通，源码才真正算你的。

跑闭环时不要上来就模拟并发。用两个客户端，一个玩家一个观察者，手动操作一遍，观察服务端日志里每个关键节点的输出：建房指令、加入指令、发牌指令、出牌广播、结算广播。任何一个节点断了，都是你排查的好机会，比自己瞎改 UI 有价值得多。

二次开发从哪下手，我推荐先改最容易看到效果的玩法参数：多局积分规则、封顶番数、机器人难度曲线。这些改完能直接在客户端里验证，成就感最强，也最能锻炼你对服务端架构的理解。等你把这些参数吃透了，再动大厅 UI 和界面布局，那属于顺水推舟的事。

有一个底线必须守住：源码可以学，可以接入自研产品做功能参考，但直接换皮上架、套名字改 Logo、拿别人的美术和文案去赚钱，都是没必要的风险。这个方向值得投入的，是你把它拆明白之后，在自己的标准化产品里重新实现的逻辑。

我见过太多人卡在同一个地方：数据库跑不起来就放弃，客户端连不上就怀疑源码是假的。其实多数问题都在配置和版本上，没有你想得那么玄。先把最小闭环跑完，再谈改造。希望上面这些踩过的坑，能帮你在同样的路上走得快一点。

本文还有配套的精品资源，点击获取