跳到主要内容

运行与预览

本页解决什么问题：帮你启动游戏预览、刷新运行画面、在浏览器里打开、点选素材，并在失败时选对恢复动作。

打开项目后，工作台顶部有 资源管理 和 运行 两个页签。运行 页签本身就是播放入口，不需要再找单独的播放按钮。

第一次运行​

  1. 点击顶部 运行。
  2. 客户端会检查项目结构、安装依赖并启动本地预览。
  3. 第一次运行通常最慢，可能需要下载依赖、构建资源和启动开发服务器。
  4. 成功后，运行画面会直接出现在工作台中间。

如果当前项目还没有可用的预览，运行页会显示提示；点击 运行 页签可以重新尝试。

提示

改完游戏代码后，预览不会像普通网页开发服务器那样自动热更新。看到新版本请点运行画面右下角的 刷新运行画面。

运行画面上的按钮​

刷新运行画面​

点击画面右下角的刷新按钮，会重新载入运行页面。它适合：

  • 改完代码后查看新版本。
  • 页面卡在旧画面。
  • 游戏重新开始一次。

刷新会重新载入页面，但不会重新安装依赖或重建项目。

全屏预览​

点击全屏按钮，只把 游戏画面 放大到全屏。顶部页签、右侧对话和底部信息栏不会一起进入全屏。

  • 再次点击按钮或按系统退出全屏方式返回。
  • 客户端或系统不支持全屏 API 时，不显示这个按钮。

在浏览器打开​

运行画面存在时，顶部会显示 在浏览器打开。它会把当前预览地址交给系统默认浏览器，适合：

  • 需要更大的窗口。
  • 需要浏览器的开发者工具。
  • 需要独立的浏览器环境测试输入和全屏。

打不开时会显示失败原因。该动作只打开新窗口，不会停止工作台里的预览。

点选素材​

单机预览运行时，顶部会出现 点选素材。

  1. 点击 点选素材。
  2. 在游戏画面中点击你想引用的区域或素材。
  3. 客户端会把该区域作为引用插入右侧陶泥儿对话。
  4. 点选模式自动退出。

这个功能适合让陶泥儿针对“画面里这一块”继续修改。点选不是编辑器，不会直接修改游戏文件，也不会改资源配置。

联机试玩时不显示点选素材按钮，避免和多个客户端标签页的手势冲突。

切换和恢复版本​

项目已有版本记录时，顶部动作区会显示版本入口，例如 版本 1、版本 2 或 当前工作区。

  1. 点击版本入口，查看可用版本。
  2. 选择一个历史版本。
  3. 客户端会先自动保存当前修改，再恢复该版本保存过的文件快照。
  4. 恢复成功后才切换当前版本。

限制和异常：

  • 没有保存 Git 文件快照的历史版本会显示「未保存 Git 快照 · 不可恢复」，不能切换。
  • 恢复前会自动保存当前修改；保存失败时不会继续覆盖。
  • 如果上次版本保存没有完成，入口会提示先完成保存，并显示 继续完成版本保存。
  • 如果上次版本切换没有完成，入口会提示其他写入已暂停，并显示 恢复切换前内容。
  • 切换版本失败时，当前版本和当前文件保持不变，错误会显示在版本菜单里。

切换版本属于本地项目版本管理，不会自动发布到陶泥儿，也不会改变线上作品版本。

联机工程试玩​

如果项目被识别为联机工程，运行页的语义会变成 本地联机试玩，不再启动普通单机预览。

  • 客户端会安装依赖、构建客户端并启动本地房间服。
  • 运行页内用标签页承载多个客户端实例。
  • 首次启动可能需要几分钟。
  • 启动过程中可以点 取消启动。
  • 启动失败时可点 重试。
  • 在浏览器打开 会打开当前选中的联机客户端，而不是单机预览地址。

联机试玩仍在本机运行，不会自动部署公网房间服。局域网、断线重连和真机体验需要单独验证。

运行失败弹窗​

启动失败时会弹出 运行失败 面板。面板会显示项目路径、一句结论和必要时截断后的原始输出。

备注

日志被截断时会明确写出还有多少字节未显示。不要把半截日志当成完整现场。

重试​

任何失败都能点 重试。如果失败只是临时网络、端口或启动抖动，重试有机会直接恢复。

重试可能需要数分钟，面板上的 关闭 始终可用。关闭面板不会中断正在进行的重试；如果再次失败，面板会重新出现。

识别项目布局 / 更新项目配置​

只有“项目结构不可用”这一类失败才显示这个按钮：

  • 项目从未记录布局时，按钮叫 识别项目布局。
  • 项目已有布局记录但可能与当前目录不一致时，按钮叫 更新项目配置。

点击后会先识别当前工程结构，确认后只更新客户端使用的项目配置，不会修改你的游戏源码。

以下情况不会显示这个按钮：

  • 引擎工程本身没有内置 Web 预览。
  • 识别过程读不到目录或文件。
  • package.json 缺少可用的 dev 脚本。
  • package.json 读不出来。

这些属于工程内容或环境问题，反复重新识别不会解决。

允许安装脚本后重试​

只有“安装依赖或启动开发服务器跑完但以非零状态结束”的命令类失败才显示。

默认安装不会执行依赖自带的安装脚本。允许后：

  • 客户端会重新启动开发服务器。
  • 只有“找不到依赖”“找不到 Vite”这类失败才会顺带重新安装。
  • 执行权限丢失、平台二进制不匹配等问题不一定能靠这一步修复。

点击过一次后，本轮不再重复显示同一个入口。

清理依赖并重装（允许安装脚本）​

这是 允许安装脚本后重试 的第二步，只有先点过它并且仍然失败时才出现；清理依赖本身失败时也可能再次出现。

清理会删掉当前项目的 node_modules，然后重新安装：

  • 删除只动依赖目录，不改锁文件和工程源文件。
  • 重新安装可能新建或更新 package-lock.json。
  • 依赖自带安装脚本仍可能写入工程文件。
  • 文件被占用或权限不足时，清理可能失败；按提示处理占用或权限后再试。

如果用户停止启动时依赖已经删除但尚未安装，面板标题会变成 运行已停止，按钮是 清理依赖并重装（允许安装脚本），表示继续把依赖装回来。

预览状态不会保存​

预览是客户端本次进程内的临时服务：

  • 退出客户端后预览一定失效。
  • 重新打开项目时，客户端只检查是否仍有活体预览。
  • 不会把预览地址写进项目配置，也不会在下次启动时假装上次还在运行。
  • 工作台里重新载入项目后，需要重新点击 运行。
注意

不要把预览地址当作正式线上地址。它只适合本机开发检查，不是发布链接。

常见失败对照​

失败现象优先动作
项目没有布局记录点 识别项目布局 并确认
目录调整后布局对不上点 更新项目配置 并确认
安装依赖失败先重试；仍失败再看 允许安装脚本后重试
启动开发服务器失败查看输出；必要时允许脚本重试
依赖损坏或反复失败走 清理依赖并重装
端口被占用关闭占用端口的程序或重启客户端后重试
Node 运行时不可用修复客户端运行环境；仅重试不会自动安装 Node
预览端口不可用释放端口或重启预览
引擎工程提示没有 Web 预览当前工程类型不走内置 Web 预览，需要单独导出或转换
联机试玩启动失败查看房间服和构建错误，修正后重试

相关页面​