Bilibili小游戏

1、概述

Bilibili小游戏（下文简称 B站小游戏）是一种运行在哔哩哔哩 App 内的免安装游戏。游戏包由平台云端托管，用户可以从游戏中心、分享链接、收藏、推荐和搜索等入口进入游戏，点开即玩。

B站小游戏支持 LayaAir 3.x。开发者在 LayaAir IDE 中选择B站小游戏并完成构建后，会得到可以导入 哔哩哔哩小游戏开发者工具 的项目工程。后续的本地调试、真机预览、上传开发版本、提交审核和发布，需要通过B站开发者工具与小游戏后台完成。

与其它小游戏平台一样，发布前需要先完成通用设置。

B站小游戏项目根目录至少需要入口文件 game.js 和配置文件 game.json，LayaAir IDE 会在构建时生成这些文件及平台适配代码。

完整流程如下：

1、注册开发者并创建小游戏；

2、在 LayaAir IDE 中配置 AppID 并构建B站小游戏工程；

3、使用B站小游戏开发者工具进行本地调试；

4、上传开发版本并扫码真机预览；

5、提交审核，审核通过后发布上线。

2、发布为B站小游戏

2.1 创建小游戏并获取 AppID

进入B站小游戏开放平台，注册成为小游戏开发者并创建小游戏。 (目前仅支持企业开发者注册) 创建完成后，在开发者后台获取 AppID，后续需要将其填写到 LayaAir IDE 的发布配置中。

后台可以为成员分别配置开发权限和预览权限：

• 拥有开发权限的成员可以上传代码包；
• 拥有预览权限的成员可以扫描开发版或审核版二维码；
• 每个小游戏最多可以添加 50 位成员，包括创建者本人。

扫码提示“无访问权限”时，应检查当前B站账号是否已加入预览成员名单，而不是重新构建项目。

2.2 选择目标平台

在 LayaAir IDE 的构建发布面板中，选择目标平台为 Bilibili小游戏，然后进入平台设置。发布前应先在通用设置中确认游戏名称、版本、屏幕方向、资源压缩和分包等选项。

B站小游戏平台设置主要包含以下参数：

App ID

填写在B站小游戏开发者后台创建应用后获得的 AppID。该值会写入构建工程的 project.config.json。上传前还应确认 game.json 中的 appId 与后台应用一致。

开放数据域

启用后，构建工程中会保留 openDataContext 目录，并在 game.json 中写入开放数据域配置。只有项目确实使用好友排行等开放数据能力时才需要开启。

开放数据域目录不能设置为分包，也不能放入其它分包中。

压缩纹理

允许使用压缩纹理格式用于控制是否采用纹理压缩设置；始终包含纹理源文件用于决定是否同时保留 png、jpg 等源纹理，以便在不支持压缩格式的设备上回退使用。

确认设置无误后执行构建，即可生成B站小游戏项目工程。 !

2.3 构建后的项目目录

LayaAir IDE 构建得到的是供B站开发者工具导入的项目工程，并不是最终上线版本。典型目录包含以下内容：

game.js

小游戏入口文件。LayaAir 引擎库、B站平台适配库、项目代码以及启动成功标记会从这里引入或调用。

game.json

B站小游戏全局配置文件，用于配置 AppID、版本、屏幕方向、网络超时、开放数据域和分包等信息。

project.config.json

开发者工具项目配置文件，包含 AppID、项目名称和开发者工具相关设置。

js、libs 与资源目录

分别用于存放项目代码、引擎库和游戏资源，实际名称会受到项目构建设置影响。

导入B站开发者工具时，应选择 LayaAir 构建生成的B站小游戏目录，不要选择 LayaAir 项目的源码根目录。

2.4 game.json 配置说明

game.json 位于小游戏项目根目录。LayaAir IDE 会根据项目与平台设置自动生成或合并配置，开发者也可以通过 build-templates/bilibili/game.json 添加项目特有配置。

属性	类型	必填	描述
version	string	是	当前小游戏版本号
appId	string	是	在B站小游戏后台获得的 AppID
deviceOrientation	string	否	portrait 为竖屏，landscape 为横屏
showStatusBar	boolean	否	是否显示状态栏，默认为 false
networkTimeout	object	否	请求、上传、下载与 WebSocket 的超时时间
openDataContext	string	否	开放数据域目录名称
subpackages	array	否	分包配置，详见第 5 节
navigateToMiniProgramAppIdList	array	否	允许跳转的小游戏 AppID，最多 10 个
iOSHighPerformance	boolean	否	iOS 高性能模式
androidHighPerformance	boolean	否	Android 高性能模式

配置示例：

{
  "version": "1.0.0",
  "appId": "biligameXXXXXXXX",
  "deviceOrientation": "landscape",
  "showStatusBar": false,
  "networkTimeout": {
    "request": 10000,
    "connectSocket": 10000,
    "uploadFile": 10000,
    "downloadFile": 10000
  }
}

build-templates/bilibili 中的同名配置会在构建时合并到平台模板。直接修改输出目录只适合临时验证；重新构建后仍需保留的配置，应放回项目构建模板中。

2.5 启动成功标记

B站小游戏要求调用 bl.launchSuccess() 上报游戏启动成功。缺少该调用可能导致开发工具上传检查失败，或者无法通过平台审核。

当前 LayaAir 的B站小游戏构建模板会在加载引擎库、项目代码和入口脚本后自动调用：

bl.launchSuccess();

构建完成后，应检查输出目录中的 game.js，确认该调用没有被自定义模板覆盖或删除。

如果项目在入口脚本加载后仍有较长的异步初始化过程，例如还需要下载首屏资源、读取存档或等待登录，应结合项目启动流程确认上报时机。游戏完成首屏初始化并进入可正常交互状态后，再报告启动成功。

警告

不要为了缩短平台统计的启动时间而过早调用 bl.launchSuccess()。它应代表玩家已经进入可用状态，而不只是入口 JavaScript 已开始执行。

3、使用B站开发者工具调试

3.1 安装开发者工具

B站官方推荐使用 哔哩哔哩小游戏开发者工具 IDE 完成本地调试、预览和上传。请从B站小游戏开发者工具说明下载并安装当前版本。

开发者工具当前建议使用 Node.js 18 或以上版本。命令行工具也可以调试和上传，但官方不推荐将其作为普通开发流程的首选方式。

3.2 导入并调试工程

1、打开B站小游戏开发者工具；

2、选择导入小游戏项目；

3、选择 LayaAir IDE 生成的B站小游戏工程目录；

4、确认项目 AppID 与B站小游戏后台一致；

5、编译运行并检查控制台输出。

本地调试时重点检查：

• JavaScript 是否存在运行错误；
• 引擎库、场景和资源路径是否正确；
• 首屏是否可以完整进入并正常交互；
• bl.launchSuccess() 是否成功执行；
• 屏幕方向、触控、音频和前后台切换是否正常；
• 网络请求与远程资源是否符合域名白名单要求。

3.3 配置服务器域名

如果小游戏需要请求业务接口、上传或下载文件、加载远程资源，或者使用 WebSocket，应在“开发者后台 → 开发 → 服务器域名”中配置对应白名单。

B站服务器域名主要有以下限制：

• request、uploadFile 和 downloadFile 只支持 HTTPS；
• connectSocket 只支持 WSS；
• 不能使用 IP 地址或 localhost；
• 域名必须完成 ICP 备案；
• 不能将 .bilibili.com 配置为开发者服务器域名；
• 每一类接口最多可以配置 20 个域名。

危险

不要把 AppSecret 写入客户端代码或随游戏包上传。需要 AppSecret 的平台接口必须由开发者自己的服务端调用。

开发者工具中的“关闭域名校验”只能用于定位问题。开发版二维码和线上环境仍会执行域名限制，提交审核前必须使用合法域名完成真机验证。

3.4 真机预览

本地运行通过后，上传或生成开发预览版本，再到小游戏后台获取预览二维码。使用已加入预览名单的B站账号扫码，在真实设备上测试。

建议至少验证：首次与二次进入、弱网环境、横竖屏与全面屏、触控区域、音频前后台状态、平台开放能力，以及 Android 与 iOS 的资源加载和性能差异。

4、上传、审核与发布

4.1 上传开发版本

在开发者工具中确认项目运行正常后，使用上传功能生成开发版本。上传时填写清晰的版本号和更新说明，便于在后台区分测试包与提审包。

上传后应在后台确认 AppID、开发版本号、上传时间和构建内容正确，并使用该版本的二维码完成真机体验。不要提交带有测试入口、无效按钮和无关调试代码的版本。

4.2 提交审核

从已经完成真机验证的开发版本发起审核，并按后台要求补齐小游戏名称、图标、介绍、截图、测试说明和必要资质。

提交前还应根据B站平台最新要求检查必接能力，例如启动成功标记、侧边栏复访能力和桌面快捷方式能力。平台能力与审核要求可能更新，请以B站官方文档和后台提示为准。

4.3 发布上线

审核通过后，在开发者后台执行发布操作，小游戏才会进入正式环境。不要将“审核通过”误认为已经自动上线。

正式发布后建议从实际投放入口再次进入游戏，确认线上版本、网络域名、资源 CDN、登录与支付环境均与预期一致。

5、分包加载

B站小游戏支持将内容拆分为主包和多个分包。首次启动时只下载主包，进入游戏后再按需加载其它分包，可以降低首包体积并缩短首次启动时间。

当前分包大小限制为：

• 游戏所有分包总大小不超过 30MB；
• 主包不超过 4MB；
• 单个分包不超过 4MB。

在 LayaAir IDE 的通用发布设置中启用分包并选择目录。发布时，B站构建插件会将分包信息写入 game.json 的 subpackages 字段。如果资源仅通过代码路径加载、没有被场景直接引用，应将其加入“始终包含的资源目录”。

LayaAir 统一使用 Laya.loader.loadPackage 加载小游戏分包：

Laya.loader.loadPackage("sub1", (progress: number) => {
    console.log("分包加载进度：", progress);
}).then(() => {
    return Laya.loader.load("sub1/Scene.ls");
}).then((sceneRes) => {
    console.log("分包资源加载完成", sceneRes);
});

底层会调用B站小游戏的 bl.loadSubpackage 接口。分包名称应与 Laya.loader.loadPackage 传入的名称保持一致。

开放数据域目录不能作为分包。存在父子嵌套目录时，应按照B站平台的分包规则安排配置顺序，并在开发者工具中检查每个分包的实际体积。

6、常见问题排查

6.1 开发者工具提示找不到 AppID

检查 LayaAir 平台设置、project.config.json 和 game.json 中的 AppID 是否与B站小游戏后台一致。重新构建前，应先修正 LayaAir 项目设置或 build-templates/bilibili 中的配置。

6.2 本地能运行，扫码后网络请求失败

通常是开发者工具关闭了域名校验，而预览版本开始执行真实白名单限制。检查协议是否为 HTTPS/WSS、域名是否备案，以及对应接口类型下是否已经添加该域名。

6.3 上传时提示缺少启动埋点

检查输出目录 game.js 中是否存在 bl.launchSuccess()。如果项目使用了自定义 game.js 模板，应将启动成功调用合并到自定义模板，并确认调用时机合理。

6.4 扫码提示无访问权限

在B站小游戏后台将扫码账号添加为预览成员。开发权限与预览权限相互独立，仅拥有上传权限不代表可以扫码体验。

6.5 重新构建后手动修改消失

不要长期直接修改构建输出目录。需要保留的 game.json、game.js 或其它平台文件，应放入 LayaAir 项目的 build-templates/bilibili 目录，由构建流程自动复制或合并。