@oppo-minigame/cli/README.md

Command line interface for rapid OPPO minigame development

# `@oppo-minigame/cli`

为开发者提供的打包 OPPO 小游戏的命令行工具, 打包前请查看 [详细教程](https://ie-activity-cn.heytapimage.com/static/minigame/CN/docs/index.html#/develop/games/quickgame)

安装 [@oppo-minigame/cli](https://www.npmjs.com/package/@oppo-minigame/cli) 后，便可使用 `quickgame` 命令。安装方法如下：

> 从 3.0.0 版本开始，仅支持 Node.js 版本 >= 16.20.2，请开发者们注意升级

```bash
npm install -g @oppo-minigame/cli
```

## 更新日志

### 2025-11-17【重要更新】
- 重要：更新版本，版本号 3.2.6
- 重要：修复 AudioClip 长音频播放失败的问题

### 2025-10-21【普通更新】
- 重要：更新版本，版本号 3.2.5
- 普通：修复微信一键转 `wx.getAccountInfoSync` 未返回 `miniProgram.version` 的问题

### 2025-10-16【重要更新】
- 重要：更新版本，版本号 3.2.4
- 重要：修复 Unity 微信一键转游戏，在 Loading 页首次加载分包时，部分机型出现耗时过久或出现崩溃、卡死的问题

### 2025-9-26【重要更新】
- 重要：更新版本，版本号 3.2.3
- 重要：修复部分微信一键转游戏无法加载 wasm 分包的问题
- 普通：修复微信一键转手动转化时，通过命令行指定参数无效的问题

### 2025-9-16【普通更新】
- 重要：更新版本，版本号 3.2.1
- 普通：修复微信一键转设置的首帧图或 logo 为空时出现的闪屏问题

### 2025-9-12【普通更新】
- 重要：更新版本，版本号 3.2.0
- 普通：新增音频适配模块，支持 InnerAudioContext 设置 src 为网络地址时，自动进行本地缓存，提升网络音频播放体验
  > 当前以外部 CommonJS 模块的形式存在，用来解决部分小游戏遇到的问题。缓存模块位于 `<node 可执行文件所在目录>/node_modules/@oppo-minigame/cli/tpl/audio/audioStreamCache.js`，请开发者们自行拷贝至项目中，并将模块注入到合适的位置
  ```javascript
  /**
   * 示例代码如下，请在尽量早的时机引入
   */

  // 引入音频缓存模块，并调用初始化方法
  require('./audioStreamCache').init({
    /**
     * 网络音频 url 所属的 cdn 地址，在此 cdn 地址下的请求才会进行缓存，请根据实际情况进行配置
     *
     * @example
     * 网络音频 url：https://test.oppo.com/resources/audio/test.mp3
     * 本地缓存 url：<本地缓存路径>/audio/test.mp3
     */
    cdn: 'https://test.oppo.com/resources'
  });
  ```

### 2025-9-11【普通更新】
- 重要：更新版本，版本号 3.1.6
- 普通：修复微信一键转 `wx.request` 默认 timeout 过短导致请求超时的问题

### 2025-9-3【普通更新】
- 重要：更新版本，版本号 3.1.3
- 普通：修复 `quickgame unity --icon` 指定图标无效的问题
- 普通：修复微信一键转设置 window.devicePixelRatio 不为 1 导致游戏未全屏的问题

### 2025-9-2【重要更新】
- 重要：更新版本，版本号 3.1.2
- 重要：新增试玩包构建功能，命令 `quickgame pack --playable`
- 重要：修复 Unity 2021 版本网络请求超时问题
- 普通：修复微信一键转 wx.onWheel、wx.offWheel 找不到的问题

### 2025-8-13【重要更新】
- 重要：更新版本，版本号 3.0.1
- 重要：修复 update-notifier require 报错的问题
- 重要：修复 Unity 2021.3.45 版本无法运行的问题

## 使用

```bash
quickgame <command> [env] [-q] [-V] [-d <pub dir>] [--help] 
```

## 参数

### `command`

#### `pack`

打包成标准小游戏工程，根据配置决定打整包还是分包

#### `transfer`

微信转 OPPO 小游戏

具体使用细节可参考 [指导文档](https://ie-activity-cn.heytapimage.com/static/minigame/CN/docs/index.html#/develop/games/wx-transfer)

#### `regedit`

注册快捷打包右键菜单项

#### `unregedit`

注销快捷打包右键菜单项

> 从 3.0.0 版本开始由于 npm7 不再支持卸载相关的钩子回调，因此无法自动移除菜单项，因此需要在卸载工具前手动调用此命令。若已卸载工具，可通过以下方式移除菜单项

- Windows

  下载 [批处理文件](https://ie-activity-cn.heytapimage.com/static/quickgame/tools/unregedit.bat)，双击运行等待完成

- Mac

  手动删除 `/Users/xxx/Library/Services` 下的 OPPO 相关 .workflow 文件

### `env`

打包 RPK 的签名版本。默认为 debug 版本，指定为 `release` 即可打包 release 版本的签名，支持的 `command` 包括 `pack`

### `-m <mode>`

生成 wasm 文件的模式 debug|optimize，默认为 debug，即调试模式，`command` 为 `wasm` 时才支持。具体说明可查看 [WebAssembly](https://ie-activity-cn.heytapimage.com/static/minigame/CN/docs/index.html#/develop/platform-tool/webAssembly)

### `-q`

生成本地二维码。该功能需要打包工具版本在 `1.0.6` 及以上，调试器版本在 `3.9.1` 及以上，支持的 `command` 包括 `pack`

### `-V`

显示打包工具版本

### `-d <pub dir>`

指定执行命令的目录，默认为当前目录。支持的 `command` 包括 `pack`, `transfer`

### `debug --log`

在控制台输出小游戏运行日志

### `--worker <workerPath>`

指定 worker 代码根目录，具体说明可查看 [通过打包工具配置](https://ie-activity-cn.heytapimage.com/static/minigame/CN/docs/index.html#/develop/performance/worker?id=通过打包工具配置)，支持的 `command` 包括 `pack`

### `--help`

是否打开命令配置详情指示

## 示例

```js
// 打包用于测试的 rpk
quickgame pack
// 打包 release 签名的 rpk
quickgame pack release

// 打二维码，用于扫码调试安装
quickgame pack -q
// 若要打 release 签名，加上 release 即可
quickgame pack release -q

// 自动转换 ts 为 wasm 文件并自动加载 wasm 文件
quickgame wasm -m debug

// 打印小游戏运行时日志
quickgame debug --log

// 微信小游戏转化为 oppo 小游戏
quickgame transfer
```
## 客服

遇到任何问题，请联系我们
<img width='30%'  src="https://ie-activity-cn.heytapimage.com/static/minigame/CN/docs/develop/games/assets/ide-talk.png" alt="微信联系方式">