Cocos Creator + ThinkPHP 搭建 H5 游戏大厅：前端、API 与服务端联调教程

这篇教程从工程部署角度拆解 Cocos Creator 前端、ThinkPHP 后台、API、数据库与服务端进程的联调流程，适合需要搭建或二次开发 H5 游戏大厅项目的朋友参考。

前言

很多 H5 游戏项目并不是单纯上传一个前端包就能运行，通常会同时包含 Cocos Creator 前端、ThinkPHP 管理后台、API 接口、数据库文件以及常驻服务端进程。部署时如果没有梳理清楚模块关系，很容易出现页面能打开但接口报错、后台能登录但游戏无法进入、资源加载正常但 WebSocket 连接失败等问题。

本文用一个通用的 H5 游戏大厅项目作为例子，整理一套偏工程化的搭建流程。重点不是单纯截图式操作，而是把目录结构、域名/IP 配置、接口联调、跨域和服务进程启动讲清楚，方便后续二次开发和排查问题。

本文仅用于合法项目部署、学习测试和内部技术研究，请确保源码、素材、业务模式和上线区域都符合当地法律法规。

一、项目模块说明

常见的 Cocos + ThinkPHP 项目一般会拆成下面几部分：

部署前建议先把源码解压到本地，确认是否存在类似目录：

728后台thinkphp/
728数据库/
728app/
728API/
728热更/
728服务端/
728前端.rar

如果目录名不同，也可以按功能去判断：有 public/index.php 的一般是 ThinkPHP 项目，有 assets/Scene 的一般是 Cocos Creator 工程，有 start.php 的一般是需要常驻运行的服务端。

二、服务器环境准备

推荐环境如下：

Nginx 1.20+
PHP 7.2 - 7.4
MySQL 5.7+
Redis 5+
Node.js 14+（如需重新构建前端）
Supervisor 或 systemd（用于守护服务进程）

PHP 扩展建议开启：

fileinfo
redis
curl
mbstring
openssl
pdo_mysql

如果使用宝塔面板，可以先创建多个站点，例如：

admin.example.com   后台管理
api.example.com     API 接口
h5.example.com      H5 前台
res.example.com     静态资源/热更新

不建议把所有模块混在同一个目录里，后期排查问题会非常麻烦。

三、导入数据库并修改配置

先创建数据库：

CREATE DATABASE h5_game DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'h5_game'@'localhost' IDENTIFIED BY '你的强密码';
GRANT ALL PRIVILEGES ON h5_game.* TO 'h5_game'@'localhost';
FLUSH PRIVILEGES;

然后导入项目自带的 SQL 文件：

mysql -u h5_game -p h5_game < ./h5_game.sql

ThinkPHP 项目通常在 .env、config/database.php 或 application/database.php 中配置数据库。建议统一使用环境变量，避免密码写死在代码里：

APP_DEBUG=false
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_NAME=h5_game
DB_USER=h5_game
DB_PASS=你的强密码
DB_PORT=3306
DB_CHARSET=utf8mb4

如果项目仍然使用数组配置，可以参考：

return [
    'type'     => env('DB_TYPE', 'mysql'),
    'hostname' => env('DB_HOST', '127.0.0.1'),
    'database' => env('DB_NAME', 'h5_game'),
    'username' => env('DB_USER', 'h5_game'),
    'password' => env('DB_PASS', ''),
    'hostport' => env('DB_PORT', '3306'),
    'charset'  => 'utf8mb4',
    'prefix'   => '',
    'debug'    => env('APP_DEBUG', false),
];

四、配置 ThinkPHP 运行目录和伪静态

ThinkPHP 项目的站点运行目录一般要指向 public：

/www/wwwroot/admin.example.com/public
/www/wwwroot/api.example.com/public

Nginx 伪静态示例：

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
        break;
    }
}

如果 API 和 H5 前端分离部署，需要开启跨域：

add_header Access-Control-Allow-Origin "*" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With" always;

if ($request_method = OPTIONS) {
    return 204;
}

上线后建议把 * 改成指定域名，例如：

add_header Access-Control-Allow-Origin "https://h5.example.com" always;

五、统一前端接口地址

Cocos Creator 项目里经常会把接口地址写在多个 JS/TS 文件中。上线前建议先全局搜索旧 IP 或旧域名：

grep -R "192.168." ./assets ./src ./build
grep -R "http://" ./assets ./src ./build

推荐抽一个统一配置文件，例如 assets/scripts/config/Env.ts：

export const Env = {
  apiBaseUrl: "https://api.example.com",
  wsUrl: "wss://api.example.com/ws",
  cdnBaseUrl: "https://res.example.com",
  version: "1.0.0",
};

请求接口时统一从配置读取：

import { Env } from "./config/Env";

export async function request(path: string, data: Record<string, unknown> = {}) {
  const res = await fetch(`${Env.apiBaseUrl}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });

  if (!res.ok) {
    throw new Error(`API request failed: ${res.status}`);
  }

  return res.json();
}

这样后续更换服务器 IP、域名或 HTTPS 证书时，只需要改一个地方。

六、接口健康检查

部署完 API 后，先不要急着打开游戏前端，可以先写一个健康检查接口：

namespace app\api\controller;

use think\facade\Db;

class Health
{
    public function index()
    {
        Db::query('SELECT 1');

        return json([
            'code' => 0,
            'msg'  => 'ok',
            'time' => date('Y-m-d H:i:s'),
        ]);
    }
}

访问：

https://api.example.com/api/health

返回类似：

{
  "code": 0,
  "msg": "ok",
  "time": "2026-08-13 15:30:00"
}

说明 PHP、Nginx、数据库基础链路已经正常。

七、启动服务端进程

如果源码中有 start.php，通常需要进入对应目录启动常驻服务：

cd /www/wwwroot/game-server
php start.php start -d

查看端口是否监听：

ss -lntp | grep php

生产环境建议用 Supervisor 守护：

[program:h5-game-server]
directory=/www/wwwroot/game-server
command=/www/server/php/74/bin/php start.php start
autostart=true
autorestart=true
startsecs=3
stdout_logfile=/www/wwwlogs/h5-game-server.log
stderr_logfile=/www/wwwlogs/h5-game-server-error.log

配置完成后执行：

supervisorctl reread
supervisorctl update
supervisorctl status

八、Cocos Creator 构建 H5

如果需要重新打包前端，可以在 Cocos Creator 中选择：

项目 -> 构建发布 -> Web Mobile

构建前重点检查：

接口域名是否替换为正式地址
WebSocket 是否使用 wss
资源服务器地址是否可访问
版本号是否更新
调试日志是否关闭

打包完成后，把构建产物上传到 H5 站点目录：

/www/wwwroot/h5.example.com/

如果打开页面后一直卡在加载页，优先检查浏览器控制台的 Network 面板，常见原因是资源 404、跨域失败或 HTTPS 混合内容。

九、常见问题排查

1. H5 页面能打开，但接口全部失败

检查 API 地址是否仍然是旧 IP：

grep -R "旧IP或旧域名" /www/wwwroot/h5.example.com

同时检查 Nginx 跨域配置是否生效。

2. 后台能登录，但前台没有游戏列表

通常是后台配置表里的 API、资源域名或游戏状态未更新。可以检查数据库中的配置表：

SELECT * FROM system_config WHERE value LIKE '%192.168.%';
SELECT * FROM game_status;

把旧地址替换为新域名后，清理缓存再测试。

3. WebSocket 连接失败

先确认端口是否开放：

ss -lntp | grep 你的端口

如果前端是 HTTPS，WebSocket 也要使用 wss://，不能继续使用 ws://。Nginx 反向代理可以参考：

location /ws {
    proxy_pass http://127.0.0.1:9501;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

4. ThinkPHP 报错目录不可写

检查运行目录权限：

chown -R www:www /www/wwwroot/api.example.com
chmod -R 755 /www/wwwroot/api.example.com
chmod -R 775 /www/wwwroot/api.example.com/runtime

5. 静态资源缓存不更新

可以给构建资源加版本号：

export const Env = {
  cdnBaseUrl: "https://res.example.com",
  assetVersion: "20260813",
};

也可以在 Nginx 中对 HTML 禁用强缓存，对图片、JS、CSS 使用长期缓存：

location = /index.html {
    add_header Cache-Control "no-cache";
}

location ~* \.(js|css|png|jpg|jpeg|webp|mp3|json)$ {
    expires 30d;
    add_header Cache-Control "public";
}

十、上线前检查清单

上线前建议逐项确认：

[ ] 所有旧 IP、旧域名已经替换
[ ] 数据库账号使用强密码
[ ] 后台入口已修改或增加访问限制
[ ] API 支持 HTTPS
[ ] WebSocket 已切换为 wss
[ ] ThinkPHP debug 已关闭
[ ] runtime/cache 已清理
[ ] 服务端进程加入守护
[ ] H5 页面在手机端测试正常
[ ] 素材图片无第三方水印或版权风险

总结

Cocos Creator + ThinkPHP 类型的 H5 项目，部署难点主要在模块拆分和地址联调。只要把前端资源、API、后台、数据库、服务端进程和热更新资源分清楚，再统一管理域名配置，后续迁移服务器、接入 HTTPS 或二次开发都会轻松很多。

如果项目部署后出现问题，建议按这个顺序排查：先看接口健康检查，再看浏览器控制台，再查服务端端口，最后检查数据库配置表。这样定位问题会比盲目重装环境更快。