尧图网页设计 
Dagger v0.21 TypeScript SDK Env 类详解环境绑定Binding与模块装配的完整 API 参考【免费下载链接】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 仓库中 v0.21 版本的 TypeScript SDK 参考文档 Env.md系统讲解Env类的构造语义、绑定Binding读写模型、with*不可变装配方法族与实验性接口并结合引擎侧源码 core/env.go 印证其在 DAG 对象体系中的实现原理帮助你把「环境」作为一等对象在自动化流程中进行编程式编排。1. Env 类定位与继承关系Env是 Dagger TypeScript SDKdagger.io/dagger生成客户端中表示运行环境的对象类型它承载一组命名的输入/输出绑定input/output bindings并允许把模块module安装进环境中、把工作区workspace挂载为宿主文件系统视图。文档明确其继承关系与方法边界ExtendsEnv继承自BaseClient因此具备生成客户端对象通用的惰性求值与 ID 语义构造函数new Env(ctx?: Context, _id?: ID): Env明确标注为「Constructor is used for internal usage only, do not create object from it」——即用户代码不应直接new Env而应通过引擎返回的Env对象例如由Client派生开始装配构造函数Overrides BaseClient.constructor_id类型引用类型别名IDID定义位于同目录type-aliases下。生成的 TypeScript 客户端源码位于 sdk/typescript/src/api/client.gen.tsEnv与其他对象类型EnvFile、EnvVariable等均由 introspection 代码生成流程统一产出这也是参考文档与源码能够逐方法对应的原因。2. 身份与绑定读取id / input / inputs / output / outputsEnv提供了两组核心读取 API2.1 id()id(): PromiseID返回该Env的唯一标识符。由于 Dagger 的对象是惰性求值的id()返回Promise在 await 后拿到稳定 ID可用于对象引用、去重与持久化定位。2.2 绑定Binding读取方法签名语义input(name)input(name: string): Binding按名称检索一个输入绑定inputs()inputs(): PromiseBinding[]返回提供给环境的全部输入绑定output(name)output(name: string): Binding按名称检索一个输出绑定outputs()outputs(): PromiseBinding[]返回环境声明的全部输出绑定绑定对象见 Binding.md。从引擎侧源码看Binding在 core/env.go 中的 Go 结构体定义为type Binding struct { Key string Value dagql.Typed Description string // The expected type // Used when defining an output ExpectedType string }这解释了 SDK 两侧参数语义的差异input 侧的description是「The purpose of the input」输入绑定的用途说明output 侧的description是「A description of the desired value of the binding」对期望取值的描述对应引擎侧ExpectedType字段注释「Used when defining an output」——即输出绑定先声明期望类型与描述实际值稍后才被赋值。这种「声明—赋值」分离正是输出绑定区别于输入绑定的关键输入是环境已持有的值输出是环境承诺要产出、但尚未求值的占位。3. 实验性接口check / checks / services文档将以下三个方法标注为Experimental使用时应注意其 API 可能随版本演进方法签名说明check(name)check(name: string): Check从已安装模块中按名返回 check必须恰好匹配一个Must match exactly one checkchecks(opts?)checks(opts?: EnvChecksOpts): CheckGroup返回已安装模块定义的全部 checkservices(opts?)services(opts?: EnvServicesOpts): UpGroup返回已安装模块定义的全部 service其中可选参数opts的类型别名分别定义在 EnvChecksOpts.md 与 EnvServicesOpts.md返回类型 Check.md、CheckGroup.md 与 UpGroup.md 的完整参考位于同一classes目录。注意check()的精确匹配约束环境中存在 0 个或多个同名 check 时不会返回「第一个」而是要求唯一命中这避免了模糊选择带来的歧义。4. with* 方法族不可变的环境装配模型Env的方法名以with开头遵循 Dagger 生成客户端的统一约定不修改当前对象返回一个新的Env。典型链路如// 伪代码示意在原环境上叠加字符串输入并声明一个输出 const env2 env .withStringInput(region, us-east-1, Deployment region) .withStringOutput(build_id, Identifier of the produced build);4.1 with(fn)链式复用with(arg: (param: Env) Env): Env文档描述「Call the provided function with current Env. This is useful for reusability and readability by not breaking the calling chain.」适用于需要「临时借用当前环境做复杂操作后继续链路」的场景避免中间变量打断调用链。4.2 输入/输出绑定方法全表31 组共 62 个方法除String外所有类型化绑定均遵循统一签名输入withXInput(name: string, value: X, description: string): Env—— 「Create or update a binding of type X in the environment」创建或更新同名的 X 类型绑定输出withXOutput(name: string, description: string): Env—— 「Declare a desired X output to be assigned in the environment」声明一个期望被赋值的 X 输出。完整类型覆盖如下按文档字母序每种类型都同时存在Input与Output两个变体绑定类型输入方法输出方法类型参考同 classes 目录AddresswithAddressInputwithAddressOutputAddress.mdCacheVolumewithCacheVolumeInputwithCacheVolumeOutputCacheVolume.mdChangesetwithChangesetInputwithChangesetOutputChangeset.mdCheckwithCheckInputwithCheckOutputCheck.mdCheckGroupwithCheckGroupInputwithCheckGroupOutputCheckGroup.mdCloudwithCloudInputwithCloudOutputCloud.mdContainerwithContainerInputwithContainerOutputContainer.mdDiffStatwithDiffStatInputwithDiffStatOutputDiffStat.mdDirectorywithDirectoryInputwithDirectoryOutputDirectory.mdEnvwithEnvInputwithEnvOutput本类EnvEnvFilewithEnvFileInputwithEnvFileOutputEnvFile.mdFilewithFileInputwithFileOutputFile.mdGeneratorwithGeneratorInputwithGeneratorOutputGenerator.mdGeneratorGroupwithGeneratorGroupInputwithGeneratorGroupOutputGeneratorGroup.mdGitRefwithGitRefInputwithGitRefOutputGitRef.mdGitRepositorywithGitRepositoryInputwithGitRepositoryOutputGitRepository.mdHTTPStatewithHTTPStateInputwithHTTPStateOutputHTTPState.mdJSONValuewithJSONValueInputwithJSONValueOutputJSONValue.mdModulewithModuleInputwithModuleOutputModule.mdModuleConfigClientwithModuleConfigClientInputwithModuleConfigClientOutputModuleConfigClient.mdModuleSourcewithModuleSourceInputwithModuleSourceOutputModuleSource.mdSearchResultwithSearchResultInputwithSearchResultOutputSearchResult.mdSearchSubmatchwithSearchSubmatchInputwithSearchSubmatchOutputSearchSubmatch.mdSecretwithSecretInputwithSecretOutputSecret.mdServicewithServiceInputwithServiceOutputService.mdSocketwithSocketInputwithSocketOutputSocket.mdStatwithStatInputwithStatOutputStat.mdStringwithStringInputwithStringOutput原生stringUpwithUpInputwithUpOutputUp.mdUpGroupwithUpGroupInputwithUpGroupOutputUpGroup.mdWorkspacewithWorkspaceInputwithWorkspaceOutputWorkspace.md4.3 参数语义约定与引擎侧字段一一对应参数类型语义namestring绑定名对应引擎Binding.Key同名重复调用即「Create orupdate」覆盖语义value对应对象类型仅 input 变体存在String类型特殊直接接收原生string而非对象descriptionstringinput 变体为输入用途说明output 变体为期望取值描述对应引擎Binding.Description/ExpectedType返回值Env新环境对象原对象不变4.4 特殊输入字符串绑定withStringInput(name: string, value: string, description: string)是唯一直接以原生string为value的方法其余类型化绑定传入的是对象引用withStringOutput(name, description)则声明期望的字符串输出。5. 模块装配与工作区withCurrentModule / withMainModule / withModule / withoutOutputs / withWorkspace这一组方法把「环境」与「模块 工作区」关联起来是 Env 区别于普通数据容器对象的关键能力5.1 模块安装方法签名语义withCurrentModule()withCurrentModule(): Env将当前模块安装进环境「exposing its functions to the model」上下文路径参数contextual path arguments将使用环境的 workspace 填充withMainModule(module_)withMainModule(module_: Module): Env设定该环境的主模块即正在被处理的项目the project being worked on上下文路径参数同样由环境 workspace 填充withModule(module_)withModule(module_: Module): Env已弃用Deprecated: Use withMainModule instead语义为把模块安装进环境并暴露其函数从文档措辞可以推断Env的模块安装面向「把模块函数暴露给模型/调用方」的场景withModule被withMainModule取代说明 API 演进后区分了「主模块」与「附加模块」两种角色。编写新代码时应直接采用withMainModule。5.2 工作区方法签名语义withWorkspace(workspace)withWorkspace(workspace: Directory): Env返回一个以给定Directory作为宿主文件系统host filesystem的新环境workspace()workspace(): Directory读取当前环境的工作区目录withWorkspace的入参是 Directory 对象文档注明其为「The directory to set as the host filesystem」与工作区语义workspace()无参返回Directory构成读写对。5.3 清空输出withoutOutputs(): Env「Returns a new environment without any outputs」——在需要剥离已声明输出、只保留输入与工作区语义的场合例如把环境作为子上下文传入另一流程使用同样返回新对象。6. 引擎侧印证与延伸阅读绑定的引擎定义core/env.go 中Binding实现了dagql.Typed所需的Type()返回Binding!与ID()以Key作为稳定对象 ID说明绑定在 DAG 缓存体系中是一个以名称为身份的轻量对象这解释了为什么input(name)可以按名直接寻址同文件中还定义了EnvHook用于把模块对象类型安装进环境 schema 的 dagql 钩子与TypesHiddenFromModuleSDKs隐藏类型列表与文档中withMainModule/withCurrentModule的「安装模块到环境」行为形成对应生成客户端实现sdk/typescript/src/api/client.gen.ts可按方法名定位Env类的实际生成代码SDK 包本身sdk/typescript/README.md 与 sdk/typescript/package.json用于确认安装与版本约束参考文档全目录Env.md 所在classes/目录下还有Binding.md、Check.md、CheckGroup.md、UpGroup.md等约 70 个类型参考type-aliases/目录下有EnvChecksOpts、EnvServicesOpts等选项别名定义。适用前提本文所有 API 签名与语义均取自 v0.21 版参考文档Env.md对应 TypeScript SDK 该版本的生成客户端check/checks/services为Experimental接口升级 SDK 时需重新核对withModule已标记弃用请以withMainModule为准构造函数为内部用途请勿手动实例化Env。【免费下载链接】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 v0.21 TypeScript SDK Env 类详解：环境绑定（Binding）与模块装配的完整 API 参考
Dagger v0.21 TypeScript SDK Env 类详解环境绑定Binding与模块装配的完整 API 参考【免费下载链接】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 仓库中 v0.21 版本的 TypeScript SDK 参考文档 Env.md系统讲解Env类的构造语义、绑定Binding读写模型、with*不可变装配方法族与实验性接口并结合引擎侧源码 core/env.go 印证其在 DAG 对象体系中的实现原理帮助你把「环境」作为一等对象在自动化流程中进行编程式编排。1. Env 类定位与继承关系Env是 Dagger TypeScript SDKdagger.io/dagger生成客户端中表示运行环境的对象类型它承载一组命名的输入/输出绑定input/output bindings并允许把模块module安装进环境中、把工作区workspace挂载为宿主文件系统视图。文档明确其继承关系与方法边界ExtendsEnv继承自BaseClient因此具备生成客户端对象通用的惰性求值与 ID 语义构造函数new Env(ctx?: Context, _id?: ID): Env明确标注为「Constructor is used for internal usage only, do not create object from it」——即用户代码不应直接new Env而应通过引擎返回的Env对象例如由Client派生开始装配构造函数Overrides BaseClient.constructor_id类型引用类型别名IDID定义位于同目录type-aliases下。生成的 TypeScript 客户端源码位于 sdk/typescript/src/api/client.gen.tsEnv与其他对象类型EnvFile、EnvVariable等均由 introspection 代码生成流程统一产出这也是参考文档与源码能够逐方法对应的原因。2. 身份与绑定读取id / input / inputs / output / outputsEnv提供了两组核心读取 API2.1 id()id(): PromiseID返回该Env的唯一标识符。由于 Dagger 的对象是惰性求值的id()返回Promise在 await 后拿到稳定 ID可用于对象引用、去重与持久化定位。2.2 绑定Binding读取方法签名语义input(name)input(name: string): Binding按名称检索一个输入绑定inputs()inputs(): PromiseBinding[]返回提供给环境的全部输入绑定output(name)output(name: string): Binding按名称检索一个输出绑定outputs()outputs(): PromiseBinding[]返回环境声明的全部输出绑定绑定对象见 Binding.md。从引擎侧源码看Binding在 core/env.go 中的 Go 结构体定义为type Binding struct { Key string Value dagql.Typed Description string // The expected type // Used when defining an output ExpectedType string }这解释了 SDK 两侧参数语义的差异input 侧的description是「The purpose of the input」输入绑定的用途说明output 侧的description是「A description of the desired value of the binding」对期望取值的描述对应引擎侧ExpectedType字段注释「Used when defining an output」——即输出绑定先声明期望类型与描述实际值稍后才被赋值。这种「声明—赋值」分离正是输出绑定区别于输入绑定的关键输入是环境已持有的值输出是环境承诺要产出、但尚未求值的占位。3. 实验性接口check / checks / services文档将以下三个方法标注为Experimental使用时应注意其 API 可能随版本演进方法签名说明check(name)check(name: string): Check从已安装模块中按名返回 check必须恰好匹配一个Must match exactly one checkchecks(opts?)checks(opts?: EnvChecksOpts): CheckGroup返回已安装模块定义的全部 checkservices(opts?)services(opts?: EnvServicesOpts): UpGroup返回已安装模块定义的全部 service其中可选参数opts的类型别名分别定义在 EnvChecksOpts.md 与 EnvServicesOpts.md返回类型 Check.md、CheckGroup.md 与 UpGroup.md 的完整参考位于同一classes目录。注意check()的精确匹配约束环境中存在 0 个或多个同名 check 时不会返回「第一个」而是要求唯一命中这避免了模糊选择带来的歧义。4. with* 方法族不可变的环境装配模型Env的方法名以with开头遵循 Dagger 生成客户端的统一约定不修改当前对象返回一个新的Env。典型链路如// 伪代码示意在原环境上叠加字符串输入并声明一个输出 const env2 env .withStringInput(region, us-east-1, Deployment region) .withStringOutput(build_id, Identifier of the produced build);4.1 with(fn)链式复用with(arg: (param: Env) Env): Env文档描述「Call the provided function with current Env. This is useful for reusability and readability by not breaking the calling chain.」适用于需要「临时借用当前环境做复杂操作后继续链路」的场景避免中间变量打断调用链。4.2 输入/输出绑定方法全表31 组共 62 个方法除String外所有类型化绑定均遵循统一签名输入withXInput(name: string, value: X, description: string): Env—— 「Create or update a binding of type X in the environment」创建或更新同名的 X 类型绑定输出withXOutput(name: string, description: string): Env—— 「Declare a desired X output to be assigned in the environment」声明一个期望被赋值的 X 输出。完整类型覆盖如下按文档字母序每种类型都同时存在Input与Output两个变体绑定类型输入方法输出方法类型参考同 classes 目录AddresswithAddressInputwithAddressOutputAddress.mdCacheVolumewithCacheVolumeInputwithCacheVolumeOutputCacheVolume.mdChangesetwithChangesetInputwithChangesetOutputChangeset.mdCheckwithCheckInputwithCheckOutputCheck.mdCheckGroupwithCheckGroupInputwithCheckGroupOutputCheckGroup.mdCloudwithCloudInputwithCloudOutputCloud.mdContainerwithContainerInputwithContainerOutputContainer.mdDiffStatwithDiffStatInputwithDiffStatOutputDiffStat.mdDirectorywithDirectoryInputwithDirectoryOutputDirectory.mdEnvwithEnvInputwithEnvOutput本类EnvEnvFilewithEnvFileInputwithEnvFileOutputEnvFile.mdFilewithFileInputwithFileOutputFile.mdGeneratorwithGeneratorInputwithGeneratorOutputGenerator.mdGeneratorGroupwithGeneratorGroupInputwithGeneratorGroupOutputGeneratorGroup.mdGitRefwithGitRefInputwithGitRefOutputGitRef.mdGitRepositorywithGitRepositoryInputwithGitRepositoryOutputGitRepository.mdHTTPStatewithHTTPStateInputwithHTTPStateOutputHTTPState.mdJSONValuewithJSONValueInputwithJSONValueOutputJSONValue.mdModulewithModuleInputwithModuleOutputModule.mdModuleConfigClientwithModuleConfigClientInputwithModuleConfigClientOutputModuleConfigClient.mdModuleSourcewithModuleSourceInputwithModuleSourceOutputModuleSource.mdSearchResultwithSearchResultInputwithSearchResultOutputSearchResult.mdSearchSubmatchwithSearchSubmatchInputwithSearchSubmatchOutputSearchSubmatch.mdSecretwithSecretInputwithSecretOutputSecret.mdServicewithServiceInputwithServiceOutputService.mdSocketwithSocketInputwithSocketOutputSocket.mdStatwithStatInputwithStatOutputStat.mdStringwithStringInputwithStringOutput原生stringUpwithUpInputwithUpOutputUp.mdUpGroupwithUpGroupInputwithUpGroupOutputUpGroup.mdWorkspacewithWorkspaceInputwithWorkspaceOutputWorkspace.md4.3 参数语义约定与引擎侧字段一一对应参数类型语义namestring绑定名对应引擎Binding.Key同名重复调用即「Create orupdate」覆盖语义value对应对象类型仅 input 变体存在String类型特殊直接接收原生string而非对象descriptionstringinput 变体为输入用途说明output 变体为期望取值描述对应引擎Binding.Description/ExpectedType返回值Env新环境对象原对象不变4.4 特殊输入字符串绑定withStringInput(name: string, value: string, description: string)是唯一直接以原生string为value的方法其余类型化绑定传入的是对象引用withStringOutput(name, description)则声明期望的字符串输出。5. 模块装配与工作区withCurrentModule / withMainModule / withModule / withoutOutputs / withWorkspace这一组方法把「环境」与「模块 工作区」关联起来是 Env 区别于普通数据容器对象的关键能力5.1 模块安装方法签名语义withCurrentModule()withCurrentModule(): Env将当前模块安装进环境「exposing its functions to the model」上下文路径参数contextual path arguments将使用环境的 workspace 填充withMainModule(module_)withMainModule(module_: Module): Env设定该环境的主模块即正在被处理的项目the project being worked on上下文路径参数同样由环境 workspace 填充withModule(module_)withModule(module_: Module): Env已弃用Deprecated: Use withMainModule instead语义为把模块安装进环境并暴露其函数从文档措辞可以推断Env的模块安装面向「把模块函数暴露给模型/调用方」的场景withModule被withMainModule取代说明 API 演进后区分了「主模块」与「附加模块」两种角色。编写新代码时应直接采用withMainModule。5.2 工作区方法签名语义withWorkspace(workspace)withWorkspace(workspace: Directory): Env返回一个以给定Directory作为宿主文件系统host filesystem的新环境workspace()workspace(): Directory读取当前环境的工作区目录withWorkspace的入参是 Directory 对象文档注明其为「The directory to set as the host filesystem」与工作区语义workspace()无参返回Directory构成读写对。5.3 清空输出withoutOutputs(): Env「Returns a new environment without any outputs」——在需要剥离已声明输出、只保留输入与工作区语义的场合例如把环境作为子上下文传入另一流程使用同样返回新对象。6. 引擎侧印证与延伸阅读绑定的引擎定义core/env.go 中Binding实现了dagql.Typed所需的Type()返回Binding!与ID()以Key作为稳定对象 ID说明绑定在 DAG 缓存体系中是一个以名称为身份的轻量对象这解释了为什么input(name)可以按名直接寻址同文件中还定义了EnvHook用于把模块对象类型安装进环境 schema 的 dagql 钩子与TypesHiddenFromModuleSDKs隐藏类型列表与文档中withMainModule/withCurrentModule的「安装模块到环境」行为形成对应生成客户端实现sdk/typescript/src/api/client.gen.ts可按方法名定位Env类的实际生成代码SDK 包本身sdk/typescript/README.md 与 sdk/typescript/package.json用于确认安装与版本约束参考文档全目录Env.md 所在classes/目录下还有Binding.md、Check.md、CheckGroup.md、UpGroup.md等约 70 个类型参考type-aliases/目录下有EnvChecksOpts、EnvServicesOpts等选项别名定义。适用前提本文所有 API 签名与语义均取自 v0.21 版参考文档Env.md对应 TypeScript SDK 该版本的生成客户端check/checks/services为Experimental接口升级 SDK 时需重新核对withModule已标记弃用请以withMainModule为准构造函数为内部用途请勿手动实例化Env。【免费下载链接】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），仅供参考