Dagger TypeScript SDK详解 ContainerExportImageOpts 与容器镜像导出选项【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger 0.21 版 TypeScript SDK 参考文档中的类型别名ContainerExportImageOpts展开完整覆盖其三个可选属性——forcedCompression、mediaTypes、platformVariants的语义与取值并结合生成客户端 client.gen.ts 与核心 schema 实现 container.go 中的参数定义说明这些选项如何影响exportImage的导出行为。读完本文你将能够正确配置镜像导出的压缩算法、媒体类型和多平台变体并理解引擎缓存对压缩策略的默认影响。类型定位ContainerExportImageOpts服务于exportImage在 Dagger TypeScript SDK 中ContainerExportImageOpts是exportImage方法的第二个可选参数类型用于把容器导出为镜像并写入宿主机本地的容器镜像仓库image store。生成客户端中的类型定义如下见 client.gen.tsexport type ContainerExportImageOpts { /** * Identifiers for other platform specific containers. * * Used for multi-platform image. */ platformVariants?: Container[] /** * Force each layer of the exported image to use the specified compression algorithm. * * If this is unset, then if a layer already has a compressed blob in the engines * cache, that will be used (this can result in a mix of compression algorithms * for different layers). If this is unset and a layer has no compressed blob in * the engines cache, then it will be compressed using Gzip. */ forcedCompression?: ImageLayerCompression /** * Use the specified media types for the exported images layers. * * Defaults to OCI, which is largely compatible with most recent container runtimes, * but Docker may be needed for older runtimes without OCI support. */ mediaTypes?: ImageMediaTypes }三个属性全部为可选optional不传任何选项时即执行默认行为。方法签名与调用方式可在 client.gen.ts 的exportImage实现中看到exportImage async ( name: string, // 宿主机镜像仓库中导出的镜像名称 opts?: ContainerExportImageOpts, ): Promisevoid { // 枚举参数通过 metadata 中的 value_to_name 映射序列化 const metadata { forcedCompression: { is_enum: true, value_to_name: ImageLayerCompressionValueToName }, mediaTypes: { is_enum: true, value_to_name: ImageMediaTypesValueToName }, } const ctx this._ctx.select(exportImage, { name, ...opts, __metadata: metadata }) await ctx.execute() }从该实现可以推断枚举参数在序列化前会经ImageLayerCompressionValueToName/ImageMediaTypesValueToName映射转换为 GraphQL 侧的枚举名字符串而platformVariants作为Container[]直接随查询一并发送。属性详解forcedCompression强制层压缩算法类型ImageLayerCompression枚举作用强制导出镜像的每一层都使用指定压缩算法。枚举全部取值见 ImageLayerCompression.md成员序列化值说明Estargz/EstarGzEStarGZeStargz 压缩支持按地址随机读取适用于镜像直接执行场景GzipGzip传统 gzip 压缩UncompressedUncompressed不压缩ZstdZstdZstandard 压缩压缩/解压速度更高该枚举存在Estargz与EstarGz两个拼写变体映射到同一个EStarGZ值属于 SDK 为兼容历史拼写保留的别名。不设置该选项时的默认行为文档原文语义与 schema 描述一致若某层在引擎缓存中已存在压缩过的 blob直接复用该缓存——这会导致同一镜像的不同层可能混用不同压缩算法若缓存中没有该层的压缩 blob则使用Gzip压缩。因此当你需要输出确定性、单一算法的镜像例如用于离线分发、合规审计或跨平台一致性校验时应显式设置forcedCompression避免“缓存里有什么就用什么”带来的不可预期结果。mediaTypes镜像层媒体类型类型ImageMediaTypes枚举作用指定导出镜像层所使用的媒体类型。枚举取值见 ImageMediaTypes.md成员序列化值Oci/OcimediaTypesOCIMediaTypesDocker/DockerMediaTypesDockerMediaTypes默认值为 OCI与绝大多数较新的容器运行时兼容只有在面向不支持 OCI 的旧版运行时时才需要切换为Docker媒体类型。与publish到远端注册表时的表述针对旧注册表相比exportImage的文档更明确地指向“宿主机容器运行时”这一消费方——因为镜像是直接落入本地镜像仓库并被本地运行时读取的。platformVariants多平台镜像变体类型Container[]作用提供其他平台对应的容器标识符用于构建多平台multi-platform镜像。典型用法是先为每个目标平台构建出一个容器再把它们作为变体传给主平台的exportImage导出的镜像即成为携带多架构 manifest 的索引镜像。例如import { Dagger, ImageLayerCompression, ImageMediaTypes } from dagger const client await Dagger.connect() const ctx client.context() // 为不同平台分别构建容器 const amd64 await ctx .container() .from(alpine) .withPlatform(linux/amd64) .withExec([echo, hello]) const arm64 await ctx .container() .from(alpine) .withPlatform(linux/arm64) .withExec([echo, hello]) // 主平台容器导出镜像其余平台作为变体 await amd64.exportImage(hello:latest, { platformVariants: [arm64], forcedCompression: ImageLayerCompression.Zstd, mediaTypes: ImageMediaTypes.Oci, })以上示例中的方法链基于 Dagger TypeScript SDK 的容器 APIexportImage的选项语义与 ContainerExportImageOpts.md 中的定义完全一致。核心实现侧的印证schema 中同名参数TypeScript SDK 的类型注释并非凭空而来而是由 Dagger 核心 schema 定义生成。在 core/schema/container.go 中exportImage的 GraphQL 节点函数声明了与 SDK 完全对应的三个参数dagql.NodeFunc(exportImage, s.exportImage). DoNotCache(Writes to the local host.). Doc(Exports the container as an image to the hosts container image store.). Args( dagql.Arg(name).Doc(Name of image to export to in the hosts store), dagql.Arg(platformVariants).Doc( Identifiers for other platform specific containers., Used for multi-platform image.), dagql.Arg(forcedCompression).Doc( Force each layer of the exported image to use the specified compression algorithm., ...), dagql.Arg(mediaTypes).Doc( Use the specified media types for the exported images layers., ...), ),两处实现事实值得关注DoNotCache(Writes to the local host.)exportImage被标记为不缓存因为它的副作用是写入宿主机本地环境。这意味着即使管道中前置步骤全部命中缓存导出动作本身仍会真正执行——选项压缩、媒体类型、变体不会因缓存而“被跳过”。同一组参数在export与publish上复用container.go 中导出 OCI tarball 的export、以及 container.go 中发布到注册表的publish均接受platformVariants、forcedCompression、mediaTypes三个同语义参数。也就是说ContainerExportImageOpts描述的压缩与媒体类型策略是 Dagger 镜像分发链路上统一的控制面理解一次即可迁移到export/publish场景。使用建议小结默认路径不传任何选项即可获得可工作的镜像——层压缩“缓存优先、缺省 Gzip”媒体类型为 OCI。日常本地开发足够。需要确定性产物显式设置forcedCompression如Zstd或Uncompressed消除“不同层混用压缩算法”的不确定性。面向旧运行时仅当目标容器运行时不支持 OCI 时才将mediaTypes设为Docker。多架构交付用platformVariants传入其他平台容器把单架构导出升级为多平台镜像索引。本文全部内容以当前仓库 0.21 版参考文档ContainerExportImageOpts.md为主体源码引用于 sdk/typescript/src/api/client.gen.ts 与 core/schema/container.go可作为后续查阅的深入路径。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Dagger TypeScript SDK：详解 ContainerExportImageOpts 与容器镜像导出选项
Dagger TypeScript SDK详解 ContainerExportImageOpts 与容器镜像导出选项【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger 0.21 版 TypeScript SDK 参考文档中的类型别名ContainerExportImageOpts展开完整覆盖其三个可选属性——forcedCompression、mediaTypes、platformVariants的语义与取值并结合生成客户端 client.gen.ts 与核心 schema 实现 container.go 中的参数定义说明这些选项如何影响exportImage的导出行为。读完本文你将能够正确配置镜像导出的压缩算法、媒体类型和多平台变体并理解引擎缓存对压缩策略的默认影响。类型定位ContainerExportImageOpts服务于exportImage在 Dagger TypeScript SDK 中ContainerExportImageOpts是exportImage方法的第二个可选参数类型用于把容器导出为镜像并写入宿主机本地的容器镜像仓库image store。生成客户端中的类型定义如下见 client.gen.tsexport type ContainerExportImageOpts { /** * Identifiers for other platform specific containers. * * Used for multi-platform image. */ platformVariants?: Container[] /** * Force each layer of the exported image to use the specified compression algorithm. * * If this is unset, then if a layer already has a compressed blob in the engines * cache, that will be used (this can result in a mix of compression algorithms * for different layers). If this is unset and a layer has no compressed blob in * the engines cache, then it will be compressed using Gzip. */ forcedCompression?: ImageLayerCompression /** * Use the specified media types for the exported images layers. * * Defaults to OCI, which is largely compatible with most recent container runtimes, * but Docker may be needed for older runtimes without OCI support. */ mediaTypes?: ImageMediaTypes }三个属性全部为可选optional不传任何选项时即执行默认行为。方法签名与调用方式可在 client.gen.ts 的exportImage实现中看到exportImage async ( name: string, // 宿主机镜像仓库中导出的镜像名称 opts?: ContainerExportImageOpts, ): Promisevoid { // 枚举参数通过 metadata 中的 value_to_name 映射序列化 const metadata { forcedCompression: { is_enum: true, value_to_name: ImageLayerCompressionValueToName }, mediaTypes: { is_enum: true, value_to_name: ImageMediaTypesValueToName }, } const ctx this._ctx.select(exportImage, { name, ...opts, __metadata: metadata }) await ctx.execute() }从该实现可以推断枚举参数在序列化前会经ImageLayerCompressionValueToName/ImageMediaTypesValueToName映射转换为 GraphQL 侧的枚举名字符串而platformVariants作为Container[]直接随查询一并发送。属性详解forcedCompression强制层压缩算法类型ImageLayerCompression枚举作用强制导出镜像的每一层都使用指定压缩算法。枚举全部取值见 ImageLayerCompression.md成员序列化值说明Estargz/EstarGzEStarGZeStargz 压缩支持按地址随机读取适用于镜像直接执行场景GzipGzip传统 gzip 压缩UncompressedUncompressed不压缩ZstdZstdZstandard 压缩压缩/解压速度更高该枚举存在Estargz与EstarGz两个拼写变体映射到同一个EStarGZ值属于 SDK 为兼容历史拼写保留的别名。不设置该选项时的默认行为文档原文语义与 schema 描述一致若某层在引擎缓存中已存在压缩过的 blob直接复用该缓存——这会导致同一镜像的不同层可能混用不同压缩算法若缓存中没有该层的压缩 blob则使用Gzip压缩。因此当你需要输出确定性、单一算法的镜像例如用于离线分发、合规审计或跨平台一致性校验时应显式设置forcedCompression避免“缓存里有什么就用什么”带来的不可预期结果。mediaTypes镜像层媒体类型类型ImageMediaTypes枚举作用指定导出镜像层所使用的媒体类型。枚举取值见 ImageMediaTypes.md成员序列化值Oci/OcimediaTypesOCIMediaTypesDocker/DockerMediaTypesDockerMediaTypes默认值为 OCI与绝大多数较新的容器运行时兼容只有在面向不支持 OCI 的旧版运行时时才需要切换为Docker媒体类型。与publish到远端注册表时的表述针对旧注册表相比exportImage的文档更明确地指向“宿主机容器运行时”这一消费方——因为镜像是直接落入本地镜像仓库并被本地运行时读取的。platformVariants多平台镜像变体类型Container[]作用提供其他平台对应的容器标识符用于构建多平台multi-platform镜像。典型用法是先为每个目标平台构建出一个容器再把它们作为变体传给主平台的exportImage导出的镜像即成为携带多架构 manifest 的索引镜像。例如import { Dagger, ImageLayerCompression, ImageMediaTypes } from dagger const client await Dagger.connect() const ctx client.context() // 为不同平台分别构建容器 const amd64 await ctx .container() .from(alpine) .withPlatform(linux/amd64) .withExec([echo, hello]) const arm64 await ctx .container() .from(alpine) .withPlatform(linux/arm64) .withExec([echo, hello]) // 主平台容器导出镜像其余平台作为变体 await amd64.exportImage(hello:latest, { platformVariants: [arm64], forcedCompression: ImageLayerCompression.Zstd, mediaTypes: ImageMediaTypes.Oci, })以上示例中的方法链基于 Dagger TypeScript SDK 的容器 APIexportImage的选项语义与 ContainerExportImageOpts.md 中的定义完全一致。核心实现侧的印证schema 中同名参数TypeScript SDK 的类型注释并非凭空而来而是由 Dagger 核心 schema 定义生成。在 core/schema/container.go 中exportImage的 GraphQL 节点函数声明了与 SDK 完全对应的三个参数dagql.NodeFunc(exportImage, s.exportImage). DoNotCache(Writes to the local host.). Doc(Exports the container as an image to the hosts container image store.). Args( dagql.Arg(name).Doc(Name of image to export to in the hosts store), dagql.Arg(platformVariants).Doc( Identifiers for other platform specific containers., Used for multi-platform image.), dagql.Arg(forcedCompression).Doc( Force each layer of the exported image to use the specified compression algorithm., ...), dagql.Arg(mediaTypes).Doc( Use the specified media types for the exported images layers., ...), ),两处实现事实值得关注DoNotCache(Writes to the local host.)exportImage被标记为不缓存因为它的副作用是写入宿主机本地环境。这意味着即使管道中前置步骤全部命中缓存导出动作本身仍会真正执行——选项压缩、媒体类型、变体不会因缓存而“被跳过”。同一组参数在export与publish上复用container.go 中导出 OCI tarball 的export、以及 container.go 中发布到注册表的publish均接受platformVariants、forcedCompression、mediaTypes三个同语义参数。也就是说ContainerExportImageOpts描述的压缩与媒体类型策略是 Dagger 镜像分发链路上统一的控制面理解一次即可迁移到export/publish场景。使用建议小结默认路径不传任何选项即可获得可工作的镜像——层压缩“缓存优先、缺省 Gzip”媒体类型为 OCI。日常本地开发足够。需要确定性产物显式设置forcedCompression如Zstd或Uncompressed消除“不同层混用压缩算法”的不确定性。面向旧运行时仅当目标容器运行时不支持 OCI 时才将mediaTypes设为Docker。多架构交付用platformVariants传入其他平台容器把单架构导出升级为多平台镜像索引。本文全部内容以当前仓库 0.21 版参考文档ContainerExportImageOpts.md为主体源码引用于 sdk/typescript/src/api/client.gen.ts 与 core/schema/container.go可作为后续查阅的深入路径。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
