@tingyun-common/cli v1.0.0

TINGYUN CLI

Tingyun CLI是用来上传Web、小程序sourcemap文件以及HarmonyOS NEXT符号表文件的CLI工具，支持Windows, Mac, Linux操作系统。

安装

方式1: npm

本地安装

1. 进入工程目录

   npm install @tingyun-common/cli

2. 验证安装成功

   npx tingyun-cli -v

如果终端中打印tingyun-cli版本证明安装成功

全局安装

1. 安装

   npm install -g @tingyun-common/cli --unsafe-perm

   需要确保有权限访问全局的node_modules目录, 如果在Linux, Mac环境遇到权限问题, 建议使用root安装

   sudo npm install -g @tingyun-common/cli --unsafe-perm

2. 验证安装成功

   tingyun-cli -v

   如果终端中打印tingyun-cli版本证明安装成功

配置可执行文件下载地址(可选)

CLI安装过程中会从服务器下载可执行文件, 可以通过--tingyuncli_cdnurl参数设置下载地址的根路径, 不配置时默认使用听云文件下载服务器地址

示例:

npm install @tingyun-common/cli --tingyuncli_cdnurl=http://example.com/path

方式2: 手动下载可执行文件

可以在听云文件下载服务器查看Tingyun CLI已经发布的版本，并根据操作系统和架构下载需要的可执行文件。下载之后可以将可执行文件重命名为tingyun-cli.exe或tingyun-cli来使用。注意可执行文件是CLI程序，需要在终端中使用。

使用

Web、小程序

1. 初始化(可选)

Tingyun CLI支持通过配置文件配置上传参数, 配置文件名为.tingyunclirc或.tingyunclirc.toml, 格式为toml格式。配置文件信息可以在听云控制台应用设置中复制或者通过运行tingyun-cli init提供的交互式信息输入工具来初始化。CLI会从当前目录或用户目录查找配置文件。

步骤:

1. 执行init命令生成配置文件.tingyunclirc.toml

   tingyun-cli init -y

   配置文件说明:

   [auth]
   # 平台access token, 应用设置获取
   token = ""
   
   [base]
   # 应用名称, 可选, 标记作用, 应用设置获取
   app_name = ""
   # 应用token, 应用设置获取
   app_token = ""
   # sourcemap上传地址, 应用设置获取
   beacon = ""
   # 产品类型, 应用设置获取
   product_type = "web"

2. 在控制台应用设置界面复制配置信息, 粘贴到.tingyunclirc.toml文件, 保存。

2. 上传sourcemap

命令:

tingyun-cli release upload <版本> <需要上传的文件或目录> --sourcemap

如果没有经过上一步初始化或不存在CLI配置文件, 可以通过参数直接传递上传所需的参数

tingyun-cli release upload <版本> <需要上传的文件或目录> --sourcemap --token=<token> --beacon=<beacon> --app-token=<appToken> --product-type=<productType>

示例:

tingyun-cli release upload V1.0.0 ./dist --sourcemap

上述命令表示上传dist目录下的sourcemap文件到V1.0.0版本下

3. 设置项目的应用版本

为了准确关联js错误, 需要通过Web或小程序SDK设置应用版本, 版本名称与CLI中设置的版本名称保持一致。当应用版本发生变化时, 需要重新通过CLI上传对应版本的sourcemap文件

Web

SDK启动时传入版本号

if (window.TINGYUN) {
  window.TINGYUN.init({
    // ...
    release: '<版本号>',
  });
}

小程序

方式1：SDK启动时传入版本号

tingyun.config({
  // ...
  releaseId: '<版本号>',
});

方式2：调用setReleaseId接口设置版本

tingyun.setReleaseId('<版本号>');

HarmonyOS NEXT

1. 上传符号表文件

命令:

1. 指定HarmonyOS NEXT工程根目录的场景

   tingyun-cli upload <工程根目录> --beacon=<beacon> --app-token=<应用token> --token=<token> --app-version=<应用版本> --build-id=<buildId> --platform=HarmonyOSNEXT

2. 指定普通目录的场景

   tingyun-cli upload <普通目录> --beacon=<beacon> --app-token=<应用token> --token=<token> --app-version=<应用版本> --build-id=<buildId> --platform=HarmonyOSNEXT --module=<模块名> --package=<包名>

说明:

1. CLI自动判断指定的目录是否是一个HarmonyOS NEXT工程的根目录。如果是则以工程根目录模式运行，否则以普通模式运行
2. 工程根目录模式下, CLI会读取app.json5文件, 尝试从app.versionName读取应用版本, 尝试从app.appEnvironments中读取tingyun_build_id环境变量，读取不到需要手动指定, 而且会自动收集当前工程下的各个模块的文件。普通模式下, 必须手动指定应用版本、buildId、module, package
3. appToken, token, 应用版本 支持通过配置文件设置或直接通过命令传递
4. 更多配置参数参考下方命令列表

2. 设置项目的应用版本

为了准确解析, 需要确保项目本身的应用版本，buildId与CLI传递的保持一致，其中应用版本在app.json5中app.versionName设置, buildId可以通过下面2种方式设置

方式1: 在app.appEnvironments中设置

{
  "app": {
    "appEnvironments": [
      {
        "name": "tingyun_build_id",
        "value": "<buildId>"
      }
    ]
  }
}

方式2: SDK启动时设置

tingyun.init({
  // ...
  buildId: '<buildId>',
});

命令列表

init

初始化配置文件

tingyun-cli init

Flags:

• -y: 跳过问卷，直接生成配置文件

release

list

展示当前版本列表

tingyun-cli release list

delete

删除版本

tingyun-cli release delete <release>

new

创建版本

tingyun-cli release new <release>

upload

上传文件

tingyun-cli release upload <release> <files>... [flags]

Flags:

• --sourcemap: 按sourcemap形式处理上传文件, 默认识别.map文件，并尝试解析.js中sourcemapping映射
• --no-overwirte: 上传不覆盖同名文件, 默认覆盖

upload

上传文件(目前仅支持HarmonyOS NEXT)

tingyun-cli upload <dir> [flags]

注: 当前仅HarmonyOS NEXT符号表上传支持此命令

Flags:

• --beacon <string>: 上传beacon地址
• --app-token <string>: 应用token(appKey)
• --token <string>: 账号token
• --app-version <string>: 应用版本
• --build-id <string>: 构建ID
• --platform <string>: 当前仅支持HarmonyOSNEXT
• --sourcemap: 仅上传sourcemap文件
• --namecache: 仅上传namecache文件
• --symbol: 仅上传so文件符号表文件
• --product <string>: 指定需要上传的product名称, 默认为default
• --target <string>: 指定需要上传的target名称, 默认为default
• --module <string>: 指定需要上传的模块的模块名(module.json5中module.name字段), 多个使用,分割
• --package <string>: 指定需要上传的模块的包名(oh-package.json5中name字段), 多个使用,分割
• --output <string>: 打包文件生成目录, 默认为当前目录下的TingyunSymbol目录
• --remove-output: 上传后删除打包文件, 默认不删除
• --no-upload: 只打包上传文件，不上报
• --upload-retries <int>: 发送失败后重试次数。默认为0次，失败后不重试

其他

查看版本

tingyun-cli -v

指定配置文件路径

Flags:

• --config <string>: 指定配置文件位置, 全局flags, 对所有命令子命令都生效。

示例:

tingyun-cli release upload V1.0.0 ./dist --sourcemap --config /my/config/dir/.tingyunclirc