先决条件
在将Vega SDK集成到CI管道中之前,请确保您的构建环境满足以下要求。请特别注意选择正确的构建主机配置,因为选择错误的构建主机配置可能会导致安装或运行时错误。系统要求
以下部分列出了在CI中构建Vega应用所支持的主机配置。主机配置
- 操作系统
- Ubuntu 20.04、22.04、24.04或26.04
- x86_64
- macOS X
- arm64(M系列)—推荐
- x86_64 (Intel)
- Ubuntu 20.04、22.04、24.04或26.04
安装过程
在CI环境中安装Vega SDK需要一种完全自动化的方法。与经常进行交互式安装的开发者工作站不同,CI环境无法依赖提示。以下部分将指导您完成此过程。基本安装
-
编辑安装命令以禁用可能中断自动安装的安装程序提示。
运行
echo $NONINTERACTIVE以确认其输出true。 -
配置所需的安装标记。
成功时,安装程序会打印确认消息并以代码
0退出。运行vega -v以确认SDK已安装且版本符合预期,然后再继续。
环境变量配置
使用以下环境变量控制安装程序脚本。Docker集成
Docker为使用Vega SDK构建应用提供了统一且隔离的环境。以下示例演示如何创建包含所有必要依赖项和配置的构建环境。这种方法适用于各种支持基于容器进行构建的CI解决方案。示例Dockerfile
验证管道中的操作系统版本兼容性
要在构建不兼容应用之前停止管道,请将vega project doctor作为构建步骤运行。请在vega project install --fix和您的程序包管理器之后、构建之前运行它。
vega project doctor在检查失败时会返回非零退出代码,因此管道步骤会失败,构建不会运行。将npm install和构建命令替换为您项目使用的程序包管理器和构建脚本。有关doctor运行的检查,请参阅vega project doctor(仅提供英文版)。
最佳实践
版本控制
- 务必使用
VEGA_SDK_VERSION在CI配置中指定确切的SDK版本。 - 使用版本固定来提高稳定性和可重现的构建。
- 存储库变更日志中的文档版本更新。
性能优化
- 在不需要设备仿真时,设置
SKIP_VVD_INSTALL=true以减少安装大小。 - 对已下载工件使用缓存策略。
- 考虑使用多阶段Docker构建,以确保较小的最终镜像。
安全性
- 请务必使用HTTPS下载网址。
- 对私有npm注册表实施适当的访问控制。
- 定期审核您的CI/CD管道配置。
故障排除
安装失败
- 验证与SDK存储库的网络连接。
- 确保有足够的磁盘空间来安装SDK。
- 检查环境变量是否设置正确。
- 确认您已在安装页面上为构建主机选择了正确的构建主机配置。
构建错误
- 验证SDK版本与您的应用程序的兼容性。
- 检查您的构建环境中是否缺少依赖关系。
- 查看构建日志以获取具体的错误消息。
- 确认您已在安装期间选择了正确的构建主机配置。
- 确认您的
manifest.toml包含[os.version]部分。缺少它时构建会失败。构建前在项目中运行vega project update-manifest --os-min 2.0 --os-version 2.0,或将相应部分添加到已提交的manifest.toml中。

