游戏引擎 / 系统课时

平台文件目录该怎样检查

平台文件目录该怎样检查

小游戏在编辑器中运行正常,导入平台开发者工具却提示入口不存在、配置无效或资源 404,通常要先核对构建产物,而不是直接改业务脚本。本课以 Cocos Creator 3.8 的微信小游戏为例,建立一套从发布目录到真机的检查顺序。

学习目标

  • 找到真正的小游戏发布根目录,分清入口、配置和资源。
  • 使用脚本验证关键文件是否齐全、JSON 是否可解析。
  • 根据报错定位目录层级、资源路径或远程部署问题。

找到实际构建产物

在 Cocos Creator 的「项目 → 构建发布」中选择微信小游戏,完成构建后,通过构建任务的文件夹按钮打开输出目录。默认可能位于 build/wechatgame,但最终以当前构建任务的发布路径为准。导入微信开发者工具时应选择包含 game.json 的小游戏工程根目录,而不是上一级 build 或 assets 子目录。

不同平台的配置文件与目录组织可能不同;下面的检查表专门针对微信小游戏,不能把它作为所有小游戏平台的强制目录标准。

区分入口、配置与资源

位置 检查内容 常见问题
game.js 小游戏启动入口存在 导入错目录、文件未生成或被误删
game.json 平台配置是合法 JSON,方向与分包声明符合预期 手工修改后语法错误、分包声明不一致
project.config.json 开发工具项目配置与 AppID 对应 测试 AppID 被带入正式发布
assets/ 本地 Asset Bundle 及其资源文件 构建资源缺失、依赖未打入
subpackages/ 启用分包后才需要核对各 Bundle 目录 配了分包但产物缺失
remote/ 启用远程 Bundle 后生成的待上传资源 只生成文件却没有部署到资源服务器

微信小游戏发布目录与远程部署的关系

assets/、subpackages/、remote/ 不一定同时出现。Cocos 的资源按 Asset Bundle 组织,包内资源通常在 assets,平台分包在 subpackages,远程 Bundle 在 remote 等待单独部署。启用分包后还要打开 game.json,核实平台分包声明和实际目录对应;不要只凭文件夹名称判断加载一定成功。

用脚本检查关键文件

将下列代码保存为 check_wechat.py,使用 Python 3 执行。它只读发布目录,不会修改构建文件;检查的是静态结构,不能代替平台工具启动测试。

python
import json
import sys
from pathlib import Path

def main():
    if len(sys.argv) != 2:
        print("用法: python check_wechat.py <PATH>")
        return 2

    root = Path(sys.argv[1]).expanduser()
    if not root.is_dir():
        print("错误: 发布目录不存在")
        return 1

    # 微信小游戏关键文件必须相对工程根目录存在。
    names = ("game.js", "game.json", "project.config.json")
    missing = [name for name in names if not (root / name).is_file()]
    if missing:
        print("缺少: " + ", ".join(missing))
        return 1

    try:
        json.loads((root / "game.json").read_text(encoding="utf-8-sig"))
        project = json.loads(
            (root / "project.config.json").read_text(encoding="utf-8-sig")
        )
    except (OSError, json.JSONDecodeError) as error:
        print(f"配置无效: {error}")
        return 1

    # 可选目录只报告状态,不当作构建失败。
    print("入口文件: 已找到 game.js")
    print("JSON 配置: 可解析")
    print("AppID: " + ("已填写" if project.get("appid") else "未填写"))
    for name in ("assets", "subpackages", "remote"):
        state = "存在" if (root / name).is_dir() else "未发现"
        print(f"{name}: {state}")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

执行 python check_wechat.py <PATH>,把 <PATH> 替换为实际发布目录;Windows 路径含空格时加引号。预期输出(以已填写 AppID、仅使用本地资源的构建为例):

text
入口文件: 已找到 game.js
JSON 配置: 可解析
AppID: 已填写
assets: 存在
subpackages: 未发现
remote: 未发现

脚本只能确认 AppID 字段非空,不能识别它是否属于目标小游戏账号,也无法证明资源引用有效。若提示缺少入口或配置,先检查路径是否指向根目录,再重新执行构建;不要靠手工新建空文件通过检查。

用平台工具验证加载链

通过静态检查后,在微信开发者工具中导入构建目录,按启动先后核对:入口能执行、首场景正常显示、点击进入非首屏场景后资源能加载。关注控制台中的缺失模块、解析错误,以及网络请求中的资源地址和状态。

遇到 404,先查 Bundle 是否构建到了预期位置、文件名大小写是否一致,再看远程资源是否已上传、URL 是否可访问。遇到分包失败,核对 game.json 的声明与 subpackages/ 的实际内容。若构建目录被手改过,优先修复 Creator 项目配置或构建模板,再重新构建,避免下次发布覆盖修复。

验收结果应同时满足:目录检查通过、开发者工具能冷启动、非首屏资源能正常加载,以及真机预览没有路径或域名相关错误。详细平台规则以 Cocos Creator 3.8 微信小游戏发布文档 为准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

平台文件目录该怎样检查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通