@taobao-minigame/cli

淘宝开放平台 CI/CD 命令行工具，支持小程序、小游戏、小部件等应用的预览与上传发布。安装后提供 tbgame 命令。

安装

npm install -g @taobao-minigame/cli

安装完成后验证：

tbgame -V
tbgame -h

快速开始

# 1. 为指定游戏设置 Token（在开放平台后台「小游戏开发 → 开发设置」获取）
tbgame config set token <appId> <token>

# 兼容旧版：设置全局兜底 Token（可选）
tbgame config set token <token>

# 2. 在项目根目录生成预览二维码
tbgame preview --appId <appId> --type minigame

# 3. 上传发布版本
tbgame upload --appId <appId> --type minigame --app-version 1.0.0

推荐按游戏配置 Token：tbgame config set token <appId> <token>。执行带 appId 的命令时优先使用该游戏的 Token，未配置时回退到旧版全局 Token。 tbgame login（Chrome 扫码登录）仍可用，但后续会下线，请尽快迁移到 Token 方式。

命令

tbgame preview

生成预览链接/二维码。

tbgame preview [options]

| 参数 | 说明 | 默认值 | | --- | --- | --- | | -i, --input <input> | 应用根目录（mini.project.json 或 app.json/package.json 所在目录） | 当前目录 | | -a, --appId <appId> | 指定应用 appId | - | | -t, --type <open_type> | 应用类型，见下方应用类型 | - | | -d, --debug | 开启真机调试 | false | | -c, --cloud | 开启云构建 | false | | --copy | 复制预览码到剪贴板 | false | | --renderMode <mode> | 小游戏渲染模式：highPerformance | normal | highPerformance | | --noBuild | 跳过云构建，使用本地缓存的上一次构建结果生成二维码（无缓存时报错，与 --cloud 互斥） | false | | --autoOpenDevtools | 真机调试拿到 DevTools 地址后自动用本地 Chrome 打开（路径取 PUPPETEER_PATH 配置，无则用系统默认 Chrome） | false |

示例：

# 最少参数:在项目根目录执行
tbgame preview --appId 1234567 --type minigame

# 最全参数:显式目录 + 真机调试 + 云构建 + 复制二维码 + 渲染模式 + 自动打开 DevTools
tbgame preview --input /path/to/project --appId 1234567 --type minigame --debug --cloud --copy --renderMode highPerformance --autoOpenDevtools

# --noBuild 与 --cloud 互斥:跳过构建,复用上次缓存生成二维码
tbgame preview --appId 1234567 --type minigame --noBuild

tbgame upload

上传发布应用。

tbgame upload [options]

| 参数 | 说明 | 默认值 | | --- | --- | --- | | -i, --input <input> | 应用根目录 | 当前目录 | | -a, --appId <appId> | 指定应用 appId | - | | -t, --type <open_type> | 应用类型，见下方应用类型 | - | | -v, --app-version <version> | 指定上传版本号；小游戏必须高于当前线上版本，不传时自动递增 | - | | --renderMode <mode> | （小游戏）渲染模式：highPerformance | normal | highPerformance |

示例：

# 最少参数:项目根目录执行,不传 --app-version 时基于线上最新版本自动递增
tbgame upload --appId 1234567 --type minigame

# 最全参数:显式指定项目目录、版本号、渲染模式
tbgame upload --input /path/to/project --appId 1234567 --type minigame --app-version 1.0.0 --renderMode highPerformance

tbgame app

获取开放平台应用的基础信息（应用名称、最新线上版本）。

tbgame app [options]

| 参数 | 说明 | 默认值 | | --- | --- | --- | | -a, --appId <appId> | 指定应用 appId | - |

示例：

# 本命令仅一个参数,最少即最全
tbgame app --appId 1234567

tbgame config

管理工具本地配置。

tbgame config set <key> <value>
tbgame config set token <appId> <token>
tbgame config get <key>
tbgame config show

| 子命令 | 说明 | | --- | --- | | config set <key> <value> | 设置配置项 | | config set token <token> | 设置兼容旧版的全局兜底 Token | | config set token <appId> <token> | 为指定游戏设置 Token，优先于全局 Token | | config get <key> | 读取配置项 | | config show | 查看全部配置；Token 值会脱敏显示 |

常用配置项：

| key | 说明 | 可选值 | | --- | --- | --- | | env | 服务环境 | prod（默认） / pre / daily | | PUPPETEER_PATH | 本地 Chrome 可执行文件路径，login 与 --autoOpenDevtools 使用 | 绝对路径 | | token | 调用凭证；推荐按 appId 配置多个游戏 Token，旧版全局 Token 仅作为兜底；login 写入全局 Token | - |

示例：

# 最少参数:查看全部配置
tbgame config show

# 读取单个配置项
tbgame config get env

# 为指定游戏设置 Token（推荐）
tbgame config set token 1234567 <token>

# 设置旧版全局兜底 Token（可选）
tbgame config set token <token>

# 最全参数:设置配置项
tbgame config set env daily
tbgame config set PUPPETEER_PATH /path/to/chrome

tbgame login

⚠️ 即将下线：请优先按游戏配置 Token（tbgame config set token <appId> <token>），login 后续版本会移除。

获取淘宝登录态。会通过本地 Chrome 打开登录页，登录成功后凭证保存在本地，供后续命令使用。

tbgame login

| 参数 | 说明 | 默认值 | | --- | --- | --- | | 无 | 本命令不接受命令行选项 | - |

登录依赖本地 Chrome。若无法自动定位，先用 tbgame config set PUPPETEER_PATH <路径> 指定。

示例：

# 最少参数:本命令无参数,直接执行
tbgame login

# 最全参数:先设置本地 Chrome 路径,再登录
tbgame config set PUPPETEER_PATH /path/to/chrome
tbgame login

应用类型

--type 参数取值（后续将专注于小游戏 minigame，其余类型逐步不再支持）：

| 应用类型 | type 取值 | 支持状态 | | --- | --- | --- | | 小游戏 | minigame | ✅ 主力支持 | | 小程序 | miniapp | ⚠️ 后续不再支持 | | 小部件 | widget | ⚠️ 后续不再支持 | | 标准化应用 | standardizedApp | ⚠️ 后续不再支持 | | 商家后台应用 | isvCMS | ⚠️ 后续不再支持 | | 配置应用 | webapp | ⚠️ 后续不再支持 |

常见问题

• 提示"当前路径没有绑定 appId"：通过 --appId 显式指定。
• 命令执行报错想看详细日志：在命令上追加 --showProcess 查看完整执行过程日志。
• 登录失败或无法拉起浏览器：先通过 tbgame config set PUPPETEER_PATH <chrome路径> 指定本地 Chrome。