小程序搬家

环境准备

Node 环境

• 推荐 node 18.x

安装 CLI

安装小程序构建 CLI 工具：

npm i -g bilibili-mp-compiler@latest

若安装时，出现如下错误：

则需要使用 sudo 命令（MAC 下）

sudo npm i -g bilibili-mp-compiler@latest

上传小程序

b 小 CLI 工具支持将微信或者抖音小程序代码，直接构建成 b 小并上传至后台，上传步骤如下：

注：目前仅支持使用微信或抖音原生小程序语法编写的小程序，暂不支持通过 uniapp 或者 taro 导出的小程序

进入小程序项目根目录（包含 app.json 的目录）

cd /path/to/miniprogram-root-dir

运行 CLI 指令：

bili-mp-compiler upload -appid 小程序的appId -v 小程序版本 -uid bilibili用户uid -desc 描述 -s 原始小程序的平台（指微信或抖音）

注：

若安装 bili-mp-compiler 时，使用了 sudo 命令，则运行 CLI 指令时，也需要添加 sudo 命令，即：

sudo bili-mp-compiler upload -appid 小程序的appId -v 小程序版本 -uid bilibili用户uid -desc 描述 -s 原始小程序的平台（指微信或抖音） |

例如，需要将微信小程序编译成 b 小，可以运行如下指令：

bili-mp-compiler upload -appid bilixxxx -v 1.0.0 -uid 1234567 -desc 测试上传 -s wx

指令参数说明：

uid 的获取方式

• 打开 bilibili App

• 点击“我的” tab

• 滚动到底部，点击“设置”，进入设置页

• 点击”账号资料“，进入账号资料页

• 账号资料页，UID 一栏，即为-uid 参数需要填写的 uid

扫码体验

上传完成后，会生成预览二维码，可以使用 bilibili App 扫码体验。

为了能正常访问小程序，有如下几点注意事项：

• bilibili App 版本：>= 8.28.0

• bilibili App 登录的账号，需要具备体验权限。体验权限的配置，可以前往如下页面进行配置：

位于：小程序详情页 -> 权限管理

• 上传后的小程序，相关请求有白名单限制，需要提前配置好，配置页同”体验权限页“：

位于：小程序详情页 -> 设置 -> 开发设置：

短剧小程序

bilibili App 版本限制

Android 和 iOS 最低版本： >= 8.33.0（预计 2.12 上市场）

插件使用方式

使用播放器插件的页面 .json 文件中添加配置项

{
  "extends": "ext://industry/playlet-plugin",
  "isPageExtension": true,
  "usingComponents": {
    "player": "xxx",
    "charge": "xxx"
  }
}

备注：player 组件模板目前不支持写入内容

tips:

小程序项目相关

• 页面目录必须是 pages 开头。

• app.json 中关于颜色的配置，仅支持完整的十六进制颜色值（#000000），不支持简写（#000）。

支付相关

• iOS 支付金额，最小单位必须为“元”，否则会支付失败（创单成功，但拉起支付面板失败）

• Android 没有最小单位限制

打开指定页面

• 若希望测试直接打开指定页面，可以在 cli 生成的 URL 中，appId 后面，追加“path/to/page”，对应参数添加至 query 中。以 appId 为 bilixxxx 的小程序为例，希望访问 pages/detail/detail 页面：

// 预览版 https://miniapp.bilibili.com/appletx/predev-bilixxxx/pages/detail/detail?query1=1&query2=2  // 线上版 https://miniapp.bilibili.com/appletx/bilixxxx/pages/detail/detail?query1=1&query2=2 |

注：若使用 -emb 1 上传的小程序，需要额外添加参数：

预览版添加： embed_base=1

线上版添加：uniapp=1

即：

// 预览版 https://miniapp.bilibili.com/appletx/predev-bilixxxx/pages/detail/detail?embed_base=1&query1=1&query2=2  // 线上版 https://miniapp.bilibili.com/appletx/bilixxxx/pages/detail/detail?uniapp=1&query1=1&query2=2

使用 onReachBottom 注意事项：

• onReachBottomDistance 设置仅支持 number 类型。

• 若需要使页面触发 onReachBottom 方法，须在页面对应的.json 文件中，添加如下配置，否则该事件不会触发：

{
  "enableScrollEvent": true
}

• page 的样式不要设置 height: 100%，否则 iOS 下，无法触发 Page.onReachBottom 事件，即：

 {
  height: 100%; // 不要设置
}

Uniapp 转 b 小

目前，b 小支持 uniapp vue2 和 vue3 版本转 b 小

使用方式：

• 更新 bilibili App， >= 8.34.0

• 更新 CLI 工具版本

npm i -g bilibili-mp-compiler@latest  // 检查版本号，确保版本号 >= 0.0.1-beta.13 bili-mp-compiler version

• 将 uniapp 项目，转成“微信小程序”：

项目根目录下，运行下面任意一条指令即可。

npm run build:mp-weixin npm run dev:mp-weixin

注：暂不支持 uniapp 转的“抖音小程序”

• 使用 CLI 工具，上传指令，上传小程序进行真机预览。

具体操作步骤，见“”。

需要特别注意的：

uniapp 小程序中，小程序项目根目录不是 uniapp 项目根目录，而是：

使用 npm run build:mp-weixin 时，根目录为： path/to/uniapp/dist/build/mp-weixin  使用 npm run dev:mp-weixin 时，根目录为： path/to/uniapp/dist/dev/mp-weixin

• 条件编译

部分场景下，开发者可能需要通过条件编译来实现不同平台小程序的差异功能。

针对 b 小，可以参考如下官方文档进行配置：

https://uniapp.dcloud.net.cn/collocation/package.html#package-json

具体配置项如下：

package.json 中，添加如下配置项：

"uni-app": {
    "scripts": {
        "mp-bili": {
            "title":"哔哩哔哩小程序",
            "env": {
                "UNI_PLATFORM": "mp-weixin"
                },
                 "define": {
                    "MP-BILI": true
                }
            }
        }
    }

配置完成后，即可在代码中添加对应的条件编译：MP-BILI

// #ifdef MP 小程序平台通用代码（含BILI） // #endif // #ifdef MP-WEIXIN 微信平台通用代码（含BILI） // #endif // #ifdef MP-BILI 哔哩哔哩平台特有代码 // #endif |

构建 bilibili 小程序，可以运行如下指令：

npm run dev:custom mp-bili npm run build:custom mp-bili

uniapp 转 b 小 功能问题处理方式

若发现 uniapp 转 b 小存在问题时，可以联系群里的相关研发同学反馈。

其中，有些问题可能涉及到 b 小框架的改动，bilibili 研发同学修复完成后，会发布一个临时版本的小程序框架。

临时版本的小程序框架发布完成后，需要内置到小程序业务代码包内后，小程序开发者方能验证修复效果。

内置方式如下：

CLI 指令追加使用 “-emb 1” 参数，即可：

bili-mp-compiler upload -appid bilixxxx -v 1.0.0 -uid 1234567 -desc 测试上传 -s wx -emb 1

Uniapp 问题汇总：

• uni-grid 和 uni-grid-item 暂时不推荐使用，会导致内容不渲染，问题我们正在排查中。

推荐使用 + flex 布局实现

• uni-popup 组件暂不支持使用，正在适配中