棋牌游戏开发技术文档：从零搭建一套可商用的房间卡棋牌架构

不少哥们儿上来就问：“棋牌游戏到底怎么搞？有没有一套能直接撸的文档？”

其实我特别理解这种心情，网上关于棋牌的资料要么停留在“单机斗地主Demo”水平，要么只丢一堆源码让你自己去猜。

正好这周把之前带团队做地方麻将、十三水、斗地主房间卡版本的经验重新梳理了一遍，今天干脆写成一份完整的棋牌游戏开发技术文档，从立项到上线，尽量还原我们当时踩过的每一道坎。读完这个，至少能帮你避开80%的无效折腾。

一、先别急着写代码，这几点想不清楚必翻车

2019年我带一个小团队接第一款棋牌外包的时候，第一周就直接按策划案开撸C++服务器，结果两个月后因为子游戏扩展性太差，全部推翻重来。从那以后我养成了一个习惯：技术文档的第一部分，永远先死磕需求和边界。

房间卡模式VS金币场
现在主流的棋牌盈利模型是“房间卡”，也就是玩家开房消耗钻石或房卡，游戏内不存在可兑换金币。从技术角度看，房间卡模式的好处是规避了赌博风控，服务端不需要设计复杂的经济系统和反洗钱策略。但代价是房间生命周期管理变得很重：需要支持实时创建、解散、续费、代开房，以及掉线重连后的状态恢复。如果你们团队还在纠结模式，优先选房间卡，政策风险小很多。

目标并发与帧同步取舍
棋牌不同于MMO，大多数子游戏都是“小消息频发”的模型。如果是地方麻将、跑得快这类回合制，3000人同时在线用长连接+可靠UDP就能扛住。但如果你要做“多人百人牛牛”这类速开桌游戏，每局仅持续几十秒，一秒内消息量可能暴涨10倍。这种情况下，帧同步还是状态同步？我们的实践经验是：棋牌尽量用状态同步，由服务器严格校验每一步操作合法性，把作弊可能性压到最低。帧同步留给纯竞技型产品，比如你自己搞个内部比赛系统还行，放到公开环境简直是灾难。

防止同一玩家多开和位置伪造
棋牌项目的安全难点从来不是“防内存修改”，而是账号维度和设备维度的关联。你需要提前规划好一套设备指纹方案，结合IP、IMEI、Android ID等多维度生成唯一标识，具体会在安全章节细说。

把上面的问题想清楚了，再去看技术选型，你会发现很多纠结自然消失了。

二、技术栈怎么搭最稳？——我用过踩坑之后的推荐

市面上棋牌技术栈千奇百怪，有拿Unity做客户端然后用纯C#写服务端的，也有用Cocos Creator配Go的。我们最终沉淀下来的这套组合，是考虑到团队招聘成本、热更新需求、服务端性能之后的折中选择：

客户端：Cocos Creator 3.x + TypeScript
服务端：Skynet（Lua） + MySQL + Redis
通信协议：Protobuf + WebSocket（强制WSS）
运维：腾讯云轻量服务器 + Docker + Jenkins自动化

为什么是Skynet而不是Java/Go？因为棋牌服务端本质上是高并发、低延迟的“房间状态机”，Skynet的Actor模型天然把一个个房间隔离成独立服务，一个房间的bug不会导致整个服务器崩溃。我们在测试环境压过单机1.6万房间同时在线，CPU稳定在60%左右。唯一门槛是Lua的弱类型，这就需要你制定严格的代码规范，以及写足够的单元测试。

客户端用Cocos Creator的原因更直接：热更新、分包加载、以及可以直接在微信小游戏和原生App间复用。你只要维护一套业务代码，打包时通过平台宏来区分API就行。

数据库选型上的一个大坑
早期我们尝试把游戏内实时分数也直接写入MySQL，结果发现出账高峰期出现了行锁死锁。后来拆成两层：MySQL只做落库存储和订单记录；Redis负责实时房间状态、玩家在线状态和临时排行。一场对局结束，先把结算数据写Redis队列，异步刷入MySQL，这个改动让数据库CPU从80%直接降到不到10%。

三、服务端核心：房间生命周期与游戏状态机

棋牌服务器的灵魂就是状态机。每个房间从“等待中→准备中→发牌中→出牌中→结算中→已结束”的流转，必须用有限状态机来严格控制。我们当时定义了一套通用的FSM框架，用Lua的闭包来实现状态切换的守卫条件。

举个例子，斗地主的“叫地主”阶段：

function state_calldz:on_enter(room)
    room:set_timeout(15, function() 
        -- 超时默认不叫
        room:broadcast("calldz_timeout", {uid = room.current_uid})
        room:move_to("playing")
    end)
end

function state_calldz:on_message(player, msg)
    if msg.cmd ~= "calldz" then return end
    if player.uid ~= room.current_uid then
        return player:send_tip("还没轮到你叫地主")
    end
    room:record_dizhu_action(player, msg.score)
    room:move_to("playing")
end

每一个状态的进入、离开、消息处理都是独立模块，新加一个子游戏比如“跑得快”，只要基于同一个FSM基类去实现对应状态即可。这种开发方式对团队新人也友好，他只需要看当前状态文件，完全不用理解其他几十个状态。

断线重连的细节
棋牌里断线重连不是简单把玩家踢回大厅，而是要让他能直接回到之前那局牌桌上，并恢复手牌、出牌记录和倒计时。我们的方案是：客户端断线后，服务器不立即清掉玩家对象，而是保留一个5分钟的“托管状态”。当客户端带着token和房间ID重连上来，服务器把当前完整牌局镜像用Protobuf一次性推过去。为了减少流量，我们做了一份增量快照压缩，把对局历史用二进制位标记，实测重连流量不超过3KB。

四、客户端那些不得不抠的体验细节

棋牌客户端最容易被忽视的，恰恰是玩家吐槽最多的点——手牌排序动画、出牌提示音顿挫、牌桌布局适配。

手牌排序与选中振动
简单把扑克牌渲染出来只完成了10%的工作。用户捏起一张牌时，它应该微微上浮，左右相邻的牌要自动让开一点间隙。我们在Cocos中实现了一个“手牌容器组件”，监听触摸开始事件，实时计算被选中的牌索引，对前后的牌做缓动偏移。这部分代码写得非常“不优雅”，充斥着大量坐标插值，但最终呈现出的手感很接近真实理牌。

多分辨率与刘海屏适配
别指望Canvas的一刀切适配。棋牌的界面元素密度高：顶部的房间号、电量显示，底部的手牌区，右侧的聊天按钮和托管开关，左边是玩家头像和分数。我们的处理方式是写了一个动态安全区组件，通过cc.screen获取实际可视区域，将主要操作区强制约束在safeArea内部。同时对于18.5:9以上的带鱼屏，牌桌背景用九宫格拉伸，保证牌不会被拉长变形。

音效管理
棋牌的音效很容易做成“噪音”。我们的原则是：出牌音和背景音乐走不同音量通道，背景音乐默认静音，只有玩家主动打开才播放；所有音效必须预加载，不允许因为音频加载导致出牌卡顿。有一版测试中，一个MP3文件采样率不对，导致安卓部分机型播放时出现100ms的阻塞，定位了两天才找到。

五、安全防护：别等被刷房了再后悔

棋牌类产品一直是黑产的重灾区。我们上线第三个月，就遭遇过一次房卡遍历攻击——黑产通过修改客户端发包，用脚本遍历房间号并尝试加入房间。

防护三板斧

所有逻辑判断必须落在服务端。玩家能不能出这张牌、赢的分数是否正确，全部由服务端算一遍。客户端只做表现和操作拦截，不做任何裁决。
通信加密与防重放。每条消息附带时间戳和自增序列号，服务端验证时间戳误差不超过3秒，序列号不能小于上次记录的序列号。我们用Protobuf的枚举字段来区分消息方向，防止黑客把服务端的回包当做请求重放回来。
行为分析与自动封禁。自研了一个简单规则引擎，统计单设备30分钟内加入房间数量、主动解散房间比例、对局中异常托管比例等指标。一旦触发阈值，直接将该设备指纹拉入风控黑名单，并生成工单推送到运营群。

另外，关于外挂透视牌的问题，服务端从发牌开始就不下发未参与玩家的手牌数据，只广播出牌结果。客户端不可能知道对手的牌，自然也透不了。

六、上线与持续运营里我踩的几个坑

小游戏过审：微信小游戏对棋牌的审核极其严格，必须提供软件著作权，并且不得有积分排名功能诱导赌博。我们的“排行”按钮改成“好友房战绩”，仅展示个人输赢局数，才勉强过审。
服务器缩容：之前配置都是按预估峰值来买，结果发现每天凌晨2点到8点几乎没人。我们在Jenkins里加了定时任务，凌晨自动将房间服务器从6台缩到2台，省了不少钱。
热更新事故：有一次热更包没做灰度，直接全量推，结果导致上万名正在对局的玩家全部弹窗提示“新版本需要重启”，投诉炸了。后来强制规定：热更新必须检查玩家是否在对局中，如果正在打牌，仅作标记，等他返回大厅再提示重载。