应用云渲染如何使用 CAR-CLI 实现应用上传及版本更新

﻿CAR-CLI 是腾讯云提供的应用版本管理命令行工具，支持开发者通过命令行方式快速完成应用的创建、版本管理、文件上传、发布上线等操作。该工具适用于桌面端应用（Application3D、ApplicationXR、ApplicationWeb）和移动端应用（ApplicationAPK）的全生命周期管理。本文将介绍 CAR-CLI 的基础功能，以及如何使用 CAR-CLI 构建流水线来实现应用版本更新的自动化。
1. 环境准备
1.1 下载 CAR-CLI 
加载远程配置文件到当前工作目录。
cd workdir
﻿
wget "your config file url"
执行如下脚本，下载命令行工具。
cd workdir
﻿
mkdir pkg && cd pkg
wget https://github.com/tencentyun/car-cli/releases/download/v1.0.0/car.zip
unzip car.zip
mv ./car/linux/car ../
cd ..
﻿
chmod +x car
1.2 配置文件要求
使用 CAR-CLI 前，需在可执行文件同级目录下放置配置文件，并将以下腾讯云账号信息替换为实际值。
配置项
说明
获取方式
SecretId
腾讯云 API 密钥 ID。
腾讯云控制台 - 访问管理。
SecretKey
腾讯云 API 密钥。
腾讯云控制台 - 访问管理。
AppId
腾讯云应用 ID。
腾讯云控制台 - 账号信息。
注意：
使用时请确保可执行文件和配置文件位于相同目录下。
1.3 基础命令
# 查看帮助信息
car help
1.4 应用版本更新流水线构建
下图为应用版本更新流水线的一个示例：
﻿
﻿
2. 核心命令详解
2.1 应用管理
2.1.1 创建应用
创建新应用，支持桌面端和移动端多种应用类型。
命令格式：
car create-application --name <应用名称> [--app-type <应用类型>]
参数说明：
参数
必填
说明
限制条件
--name
是
应用名称
16字符以内，仅支持中文、字母、数字或连接符 -。
--app-type
否
应用类型
不传时默认创建桌面端 Application3D。
支持的应用类型：
应用类型
适用场景
平台
Application3D
3D 桌面应用。
桌面端
ApplicationXR
XR 扩展现实应用。
桌面端
ApplicationWeb
Web 桌面应用。
桌面端
ApplicationAPK
Android 移动应用。
移动端
使用示例：
# 创建桌面端应用（默认类型）
car create-application --name my-desktop-app
﻿
# 创建移动端应用
car create-application --name my-mobile-app --app-type ApplicationAPK
2.2 版本管理
2.2.1 创建应用版本
为指定应用创建新版本，同一应用下版本创建数量上限为 5 个。
命令格式：
car create-application-version --app-id <应用ID> --name <版本名称> --type <包格式> [--regions <分发地区>] [--update-mode <更新方式>]
参数说明：
参数
必填
说明
适用平台
--app-id
是
应用 ID。
全平台
--name
是
版本命名。
全平台
--type
是
包文件类型。
全平台
--regions
否
分发地区列表。
仅桌面端
--update-mode
否
更新方式。
仅桌面端
包文件类型支持：
平台
支持格式
说明
桌面端
zip、rar、7z
压缩包格式。
移动端
apk、xapk、zip
Android 安装包格式。
注意事项：
若存在"创建中/待发布/创建失败"状态的版本，操作会被拒绝。
--regions 和 --update-mode 参数仅桌面端生效，移动端无需传入。
最终格式合法性由后端根据应用实际类型校验。
使用示例：
# 桌面端：创建全量更新版本，分发至中国大陆和东京
car create-application-version --app-id app-xxx --name v1.0.0 --type zip --regions ap-chinese-mainland,ap-tokyo --update-mode FULL
﻿
# 移动端：创建新版本
car create-application-version --app-id app-xxx --name mobile-v1 --type apk
2.2.2 上传应用版本文件
上传应用包文件到指定版本，支持本地文件路径和 URL 两种方式。
命令格式：
# 本地文件上传
car upload-application-version-file --app-id <应用ID> --version-id <版本ID> --path <本地路径>
﻿
# URL 上传
car upload-application-version-file --app-id <应用ID> --url <文件URL>
参数说明：
参数
必填
说明
注意事项
--app-id
是
应用 ID。
需与创建时一致。
--version-id
是
应用版本 ID。
本地上传时必填。
--path
是（本地）
本地文件路径。
注意 Windows 和 Linux 路径格式差异。
--url
是（URL）
文件下载地址。
URL 上传时只需此参数。
路径格式示例：
操作系统
路径格式示例
Windows
C:\\data\\myapp.zip
Linux/macOS
/data/myapp.apk
使用示例：
# Windows 本地文件上传
car upload-application-version-file --app-id app-xxx --path C:\\data\\xxx.zip --version-id ver-xxx
﻿
# Linux 本地文件上传
car upload-application-version-file --app-id app-xxx --path /data/xxx.apk --version-id ver-xxx
﻿
# URL 上传
car upload-application-version-file --app-id app-xxx --url https://example.com/app.zip
注意：
上传成功后，版本名称和包格式会被替换为所上传文件的名字和格式。
2.2.3 发布应用版本
将指定版本发布上线，使其对用户可见。
命令格式：
car set-version-online --app-id <应用ID> --version-id <版本ID>
参数说明：
参数
必填
说明
--app-id
是
应用 ID。
--version-id
是
应用版本 ID。
平台差异：
平台
发布前校验
说明
桌面端
校验启动路径。
需确保启动路径配置正确。
移动端
自动跳过校验。
无需额外配置。
使用示例：
car set-version-online --app-id app-xxx --version-id ver-xxx
2.2.4 删除应用版本
异步删除指定版本，删除后可通过查询版本列表确认状态。
命令格式：
car delete-application-version --app-id <应用ID> --version-id <版本ID>
参数说明：
参数
必填
说明
--app-id
是
应用 ID。
--version-id
是
应用版本 ID。
使用示例：
car delete-application-version --app-id app-xxx --version-id ver-xxx
2.2.5 查询应用版本列表
展示指定应用的所有版本信息，包括版本 ID 和版本状态。
命令格式：
car describe-application-version --app-id <应用ID>
参数说明：
参数
必填
说明
--app-id
是
应用 ID。
高级用法：结合 grep 和 awk 命令获取最旧版本。
# 获取最旧版本（排除正在使用的版本）
car describe-application-version --app-id app-xxx | grep -v "Inuse" | awk '{print $1}' | head -n 1
使用示例：
# 查询所有版本
car describe-application-version --app-id app-xxx
﻿
# 获取最旧版本 ID
car describe-application-version --app-id app-xxx | grep -v "Inuse" | awk '{print $1}' | head -n 1
3. 桌面端与移动端差异对比
3.1 功能差异总览
功能模块
桌面端
移动端
说明
应用类型
Application3D
ApplicationXR
ApplicationWeb
ApplicationAPK
创建时需指定。
包格式
zip、rar、7z
apk、xapk、zip
后端校验。
分发地区
支持
不支持
--regions 仅桌面端。
更新方式
支持全量更新
不支持
--update-mode 仅桌面端。
发布校验
校验启动路径
自动跳过
平台差异。
3.2 命令参数差异详情
3.2.1 create-application 命令
参数
桌面端
移动端
说明
--name
必填
必填
应用名称。
--app-type
可选（默认 Application3D）
必填 ApplicationAPK
应用类型。
3.2.2 create-application-version 命令
参数
桌面端
移动端
说明
--app-id
必填
必填
应用 ID。
--name
必填
必填
版本名称。
--type
必填
必填
包格式。
--regions
可选
不支持
分发地区。
--update-mode
可选
不支持
更新方式。
3.2.3 set-version-online 命令
校验项
桌面端
移动端
启动路径
强制校验。
自动跳过。
4. 版本分发地区
4.1 地区列表
地区代码
地区名称
类型
ap-chinese-mainland
中国大陆
大陆默认
ap-tokyo
东京标准区
国际默认
ap-tokyo-fusion
东京融合区
融合区
ap-seoul
首尔标准区
标准区
ap-seoul-fusion
首尔融合区
融合区
ap-singapore
新加坡标准区
标准区
ap-singapore-fusion
新加坡融合区
融合区
eu-frankfurt
法兰克福标准区
标准区
eu-frankfurt-fusion
法兰克福融合区
融合区
na-north-america
北美标准区
标准区
na-north-america-fusion
北美融合区
融合区
me-middle-east-fusion
中东融合区
融合区
sa-south-america-fusion
南美融合区
融合区
4.2 地区选择建议
中国大陆用户：选择 ap-chinese-mainland。
国际用户：选择就近的标准区或融合区。
多地区分发：可传入多个地区代码，用逗号分隔。
5. 完整使用流程示例
5.1 桌面端应用完整流程
# 1. 创建桌面端应用
car create-application --name my-desktop-app
﻿
# 2. 创建新版本（全量更新，分发至中国大陆和东京）
car create-application-version --app-id app-xxx --name v1.0.0 --type zip --regions ap-chinese-mainland,ap-tokyo --update-mode FULL
﻿
# 3. 上传应用包
car upload-application-version-file --app-id app-xxx --version-id ver-xxx --path /data/myapp.zip
﻿
# 4. 发布上线
car set-version-online --app-id app-xxx --version-id ver-xxx
5.2 移动端应用完整流程
# 1. 创建移动端应用
car create-application --name my-mobile-app --app-type ApplicationAPK
﻿
# 2. 创建新版本（无需 regions 和 update-mode）
car create-application-version --app-id app-xxx --name v1.0.0 --type apk
﻿
# 3. 上传应用包
car upload-application-version-file --app-id app-xxx --version-id ver-xxx --path /data/myapp.apk
﻿
# 4. 发布上线
car set-version-online --app-id app-xxx --version-id ver-xxx
5.3 版本管理自动化脚本
﻿
cd workdir
﻿
# 查询对应应用的版本列表
output=$(./car describe-application-version --app-id $ApplicationID)   #流水线环境变量配置ApplicationID
lineCount=$(echo "$output" | wc -l)
﻿
# 若版本数量大于5，则删除旧版本
if [ $lineCount -ge 5 ];then
    versionID=$(echo "$output" | grep -v "Inuse" | awk '{print $1}' | head -n 1)
    ./car delete-application-version --app-id $ApplicationID --version-id $versionID
fi
﻿
# 因删除应用版本是异步操作，所以定时查询版本是否删除成功
waitTimes=0
while [ $lineCount -ge 5 ]
do
    output=$(./car describe-application-version --app-id $ApplicationID)   #替换为自己ApplicationID
    lineCount=$(echo "$output" | wc -l)
    
    waitTimes=$((waitTimes+1))
    if [ $waitTimes -gt 20 ]
    then
        echo "Error: Waiting too long to delete application version."
        exit 1
    fi
    
    sleep 1
done
﻿
# 根据PackageURL查询包名称和包类型
fileName=$(basename $PackageURL)         # 流水线环境变量配置PackageURL
echo $fileName
fileType="${PackageURL##*.}"
echo $fileType
﻿
# 创建新版本
output=$(./car create-application-version --app-id $ApplicationID --name $fileName --type $fileType)
﻿
# 上传新版本应用到云端
./car upload-application-version-file --app-id $ApplicationID --version-id $output --path $fileName
﻿
# 发布新版本
./car set-version-online --app-id $ApplicationID --version-id $output
6. 常见问题与注意事项
6.1 版本数量限制
同一应用下版本创建数量上限为 5 个。
若存在"创建中/待发布/创建失败"状态的版本，新创建操作会被拒绝。
建议定期清理旧版本，保持版本列表整洁。
6.2 路径格式注意
Windows：使用反斜杠 \\，如 C:\\data\\app.zip。
Linux/macOS：使用正斜杠 /，如 /data/app.zip。
建议脚本中根据操作系统自动适配路径格式。
6.3 上传后版本信息变更
上传应用包成功后：
版本名称会被替换为上传文件的文件名。
包格式会被替换为上传文件的实际格式。
请在发布前确认版本信息正确。
6.4 异步操作说明
删除版本为异步操作，执行后需通过查询版本列表确认删除状态。
建议脚本中添加轮询检查逻辑，确保操作完成后再执行后续步骤。

配置项	说明	获取方式
SecretId	腾讯云 API 密钥 ID。	腾讯云控制台 - 访问管理。
SecretKey	腾讯云 API 密钥。	腾讯云控制台 - 访问管理。
AppId	腾讯云应用 ID。	腾讯云控制台 - 账号信息。

参数	必填	说明	限制条件
--name	是	应用名称	16字符以内，仅支持中文、字母、数字或连接符 `-`。
--app-type	否	应用类型	不传时默认创建桌面端 `Application3D`。

应用类型	适用场景	平台
Application3D	3D 桌面应用。	桌面端
ApplicationXR	XR 扩展现实应用。	桌面端
ApplicationWeb	Web 桌面应用。	桌面端
ApplicationAPK	Android 移动应用。	移动端

平台	支持格式	说明
桌面端	zip、rar、7z	压缩包格式。
移动端	apk、xapk、zip	Android 安装包格式。

操作系统	路径格式示例
Windows	`C:\\data\\myapp.zip`
Linux/macOS	`/data/myapp.apk`

平台	发布前校验	说明
桌面端	校验启动路径。	需确保启动路径配置正确。
移动端	自动跳过校验。	无需额外配置。

功能模块	桌面端	移动端	说明
应用类型	Application3D ApplicationXR ApplicationWeb	ApplicationAPK	创建时需指定。
包格式	zip、rar、7z	apk、xapk、zip	后端校验。
分发地区	支持	不支持	--regions 仅桌面端。
更新方式	支持全量更新	不支持	--update-mode 仅桌面端。
发布校验	校验启动路径	自动跳过	平台差异。

校验项	桌面端	移动端
启动路径	强制校验。	自动跳过。

地区代码	地区名称	类型
ap-chinese-mainland	中国大陆	大陆默认
ap-tokyo	东京标准区	国际默认
ap-tokyo-fusion	东京融合区	融合区
ap-seoul	首尔标准区	标准区
ap-seoul-fusion	首尔融合区	融合区
ap-singapore	新加坡标准区	标准区
ap-singapore-fusion	新加坡融合区	融合区
eu-frankfurt	法兰克福标准区	标准区
eu-frankfurt-fusion	法兰克福融合区	融合区
na-north-america	北美标准区	标准区
na-north-america-fusion	北美融合区	融合区
me-middle-east-fusion	中东融合区	融合区
sa-south-america-fusion	南美融合区	融合区

如何使用 CAR-CLI 实现应用上传及版本更新

本页目录：

1. 环境准备

1.1 下载 CAR-CLI

1.2 配置文件要求

1.3 基础命令

1.4 应用版本更新流水线构建

2. 核心命令详解

2.1 应用管理

2.1.1 创建应用

2.2 版本管理

2.2.1 创建应用版本

2.2.2 上传应用版本文件

2.2.3 发布应用版本

2.2.4 删除应用版本

2.2.5 查询应用版本列表

3. 桌面端与移动端差异对比

3.1 功能差异总览

3.2 命令参数差异详情

3.2.1 create-application 命令

3.2.2 create-application-version 命令

3.2.3 set-version-online 命令

4. 版本分发地区

4.1 地区列表

4.2 地区选择建议

5. 完整使用流程示例

5.1 桌面端应用完整流程

5.2 移动端应用完整流程

5.3 版本管理自动化脚本

6. 常见问题与注意事项

6.1 版本数量限制

6.2 路径格式注意

6.3 上传后版本信息变更

6.4 异步操作说明