Dagger TypeScript SDK 的 EnvVariable 类容器环境变量对象化读取与实战指南【免费下载链接】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 官方 TypeScript SDKdagger.io/dagger中生成的 API 客户端类EnvVariable展开讲解它如何以名称 值的对象形态描述容器中的持久环境变量以及如何通过Container.envVariable()与Container.envVariables()获取其实例并配合withEnvVariable(expand)理解$VAR展开机制。读完本文你将掌握在 Dagger 管道中用 TypeScript 查询、遍历和校验容器环境变量的完整方法并能结合仓库源码理解其底层实现。EnvVariable 类概览一句话理解它的定位在 Dagger TypeScript SDK 的 API 文档 中EnvVariable被定义为一个非常轻量的类其官方注释为An environment variable name and value.即一个环境变量的名称和值。它本身不包含任何操作容器的方法只负责把容器中某个环境变量的两个最基础属性——name名称与value值——封装成一个可查询的对象。它是 Dagger GraphQL API 中EnvVariable类型在 TypeScript 侧的客户端映射属于自动生成的client.gen.ts而非手写业务代码。从源码看sdk/typescript/src/api/client.gen.ts 中类的定义非常精简/** * An environment variable name and value. */ export class EnvVariable extends BaseClient { private readonly _id?: ID undefined private readonly _name?: string undefined private readonly _value?: string undefined // ... }类继承自BaseClient内部只缓存了id、name、value三个私有字段全部为只读体现了它纯数据查询的定位。核心 API 详解id / name / value 三个方法EnvVariable对外暴露三个异步方法全部返回Promise这与 Dagger 的惰性求值模型一致——调用方法时才真正向引擎发起 GraphQL 查询。id(): PromiseEnvVariableIDA unique identifier for this EnvVariable.返回该环境变量对象的唯一标识符。其类型为EnvVariableID在 EnvVariableID 类型别名文档 中定义为type EnvVariableID string { __EnvVariableID: never }它是一个以string为基础、通过__EnvVariableID: never做名义类型标记nominal typing的标量类型用于在编译期防止不同类型的 ID 相互混用。id()通常用于持久化场景——例如把某个环境变量对象的 ID 保存下来后续通过client.loadEnvVariableFromID(id)重新加载若 SDK 暴露了对应加载方法从而避免反复重建查询链路。name(): PromisestringThe environment variable name.返回环境变量的名称Key例如PATH、FOO。这是区分不同环境变量的唯一标识。value(): PromisestringThe environment variable value.返回环境变量的值Value例如/usr/local/sbin:/usr/local/bin。需要注意Dagger 中的EnvVariable仅表示持久化在容器配置image config /withEnvVariable写入中的环境变量它并不包含容器运行时如withExec中env参数注入的临时变量产生的全部环境。构造函数仅供内部使用Constructor is used for internal usage only, do not create object from it.构造函数签名为new EnvVariable(ctx?, _id?, _name?, _value?)其中ctx?: Context为 Dagger 查询上下文其余三个下划线前缀参数分别对应该对象缓存的 ID、名称和值。文档明确警告不要自行 new 该对象实例只能由 SDK 内部如Container.envVariables()构造。EnvVariable 从何而来与 Container API 的配套关系EnvVariable永远不会独立存在它总是作为Container的查询结果出现。理解它必须先理解配套的三个Container方法均在同一份 client.gen.ts 中生成1. 写入withEnvVariable(name, value, opts?)withEnvVariable 用于在容器中设置一个新的环境变量返回一个新的Container不可变快照语义签名如下withEnvVariable ( name: string, value: string, opts?: ContainerWithEnvVariableOpts, ): Container { const ctx this._ctx.select(withEnvVariable, { name, value, ...opts }) return new Container(ctx) }参数说明name环境变量名如HOSTvalue环境变量值如localhostopts.expand是否展开值中的$VAR/${VAR}详见下文 expand 一节。2. 查询单个envVariable(name): PromisestringenvVariable 按名称直接返回字符串值注意返回的不是EnvVariable对象而是string适合只关心某个变量的值的场景envVariable async (name: string): Promisestring { if (this._envVariable) { return this._envVariable } const ctx this._ctx.select(envVariable, { name }) const response: Awaitedstring await ctx.execute() return response }3. 查询列表envVariables(): PromiseEnvVariable[]envVariables 返回EnvVariable[]数组是唯一合法获取EnvVariable实例的入口。其实现体现了 Dagger 的查询优化技巧——先只请求每个元素的id再通过selectNode按 ID 重建各自的查询上下文从而让后续对name()/value()的调用可以按需懒加载envVariables async (): PromiseEnvVariable[] { type envVariables { id: ID } const ctx this._ctx.select(envVariables).select(id) const response: AwaitedenvVariables[] await ctx.execute() return response.map( (r) new EnvVariable(ctx.copy().selectNode(r.id, EnvVariable)), ) }expand 选项$VAR 展开机制的源码级解读EnvVariable的值可以是字面值也可以是引用其他变量的模板。何时展开由 ContainerWithEnvVariableOpts 中的expand?布尔选项控制Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g. /opt/bin:$PATH).即当expand: true时withEnvVariable(PATH_EXT, /opt/bin:$PATH)会把$PATH展开为容器当前已有的PATH值expand缺省为false值中的$VAR会原样保留此时$不会转义通常需要手动写\$或直接使用字面值。底层实现位于引擎侧 core/container.go 的ExpandContainerInputfunc ExpandContainerInput(container *Container, input string, expand bool) (string, error) { if !expand { return input, nil } // 收集容器中的 Secret 与 volatile 环境变量禁止对其展开 expanded : os.Expand(input, func(k string) string { if slices.Contains(secretEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with secret env variable %q, k) return } if slices.Contains(volatileEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with volatile env variable %q, k) return } v, _ : LookupEnv(container.Config.Env, k) return v }) // ... }从源码可以归纳出三个关键实现事实展开基于os.Expand支持$VAR与${VAR}两种写法查找范围是容器的Config.Env即当前容器配置中已持久化的环境变量而不是宿主机环境Secret 与 volatile 变量禁止展开若引用了密钥类或易变volatile环境变量引擎会直接报错expand cannot be used with secret env variable/expand cannot be used with volatile env variable这是一种安全设计避免把敏感值意外拼入普通环境变量。引擎侧持久化该操作时也记录了Expand字段见 core/container.go 中的persistedContainerWithEnvVariableLazy。另外需要注意EnvVariable对象本身展示的是展开后的持久化值envVariables()不会返回容器内 secret 注入的临时变量Secret 在 Dagger 中由独立的Secret类型管理不混入EnvVariable列表。实战示例完整可运行的 TypeScript 代码下面是一个基于alpine镜像、覆盖写入 → 展开 → 列表 → 单项读取全流程的示例import { connect } from dagger.io/dagger connect(async (client) { const ctr client .container() .from(alpine:3.16.2) .withEnvVariable(FOO, TCP) // 字面值 .withEnvVariable(BAR, BOOL) .withEnvVariable(PATH_EXT, /opt/bin:$PATH, { expand: true }) // 展开 $PATH // 1) 按名称读取单个变量返回 string const foo await ctr.envVariable(FOO) console.log(FOO , foo) // TCP // 2) 读取全部持久化环境变量返回 EnvVariable[] const envs await ctr.envVariables() for (const env of envs) { console.log(await env.name(), , await env.value()) } // 3) 在 exec 中使用这些变量验证展开结果 const out await ctr.withExec([printenv, PATH_EXT]).stdout() console.log(PATH_EXT , out.trim()) })注意envVariables()返回的元素类型是EnvVariable需要分别调用其name()与value()均为异步方法才能拿到实际值而envVariable(name)一步到位返回string。若你只需要一个变量的值优先用后者能少一次 GraphQL 往返。测试用例佐证SDK 中的真实行为仓库自带的 SDK 测试 sdk/typescript/src/api/test/api.spec.ts 印证了上述行为链式写入const env (c: Container): Container c.withEnvVariable(FOO, bar)L260-L263说明withEnvVariable返回新容器、可参与函数组合空值与 exec 可见性withEnvVariable(FOO, )之后执行withExec([printenv, FOO])输出为空行L296-L302证明空字符串也是合法值且会被 exec 看到列表遍历连续设置FOOBAR、BARBOOL后调用ctr.envVariables()逐一断言L366-L372与上文envVariables()的用法完全一致单项读取withEnvVariable(FOO, TCP)后envVariable(FOO)断言等于TCPL388-L394。小结与使用建议EnvVariable是 Dagger TypeScript SDK 中最基础的数据对象之一设计极其克制它只回答容器里持久化了哪些环境变量、叫什么、值是什么这三个问题。实践中请记住四条准则不要手动new EnvVariable只通过Container.envVariables()获取实例取单个值用Container.envVariable(name)返回string取全量再遍历EnvVariable的name()/value()涉及$VAR展开时显式传{ expand: true }且不要尝试展开 Secret 或 volatile 变量引擎会拒绝执行该对象只反映持久化配置容器运行期动态产生的临时环境不在此列。相关 API 文档与源码索引类定义见 EnvVariable 类文档 与 client.gen.tsID 类型见 EnvVariableID展开语义可继续深入引擎源码 core/container.go 与 SDK 测试 api.spec.ts。【免费下载链接】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 的 EnvVariable 类：容器环境变量对象化读取与实战指南
Dagger TypeScript SDK 的 EnvVariable 类容器环境变量对象化读取与实战指南【免费下载链接】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 官方 TypeScript SDKdagger.io/dagger中生成的 API 客户端类EnvVariable展开讲解它如何以名称 值的对象形态描述容器中的持久环境变量以及如何通过Container.envVariable()与Container.envVariables()获取其实例并配合withEnvVariable(expand)理解$VAR展开机制。读完本文你将掌握在 Dagger 管道中用 TypeScript 查询、遍历和校验容器环境变量的完整方法并能结合仓库源码理解其底层实现。EnvVariable 类概览一句话理解它的定位在 Dagger TypeScript SDK 的 API 文档 中EnvVariable被定义为一个非常轻量的类其官方注释为An environment variable name and value.即一个环境变量的名称和值。它本身不包含任何操作容器的方法只负责把容器中某个环境变量的两个最基础属性——name名称与value值——封装成一个可查询的对象。它是 Dagger GraphQL API 中EnvVariable类型在 TypeScript 侧的客户端映射属于自动生成的client.gen.ts而非手写业务代码。从源码看sdk/typescript/src/api/client.gen.ts 中类的定义非常精简/** * An environment variable name and value. */ export class EnvVariable extends BaseClient { private readonly _id?: ID undefined private readonly _name?: string undefined private readonly _value?: string undefined // ... }类继承自BaseClient内部只缓存了id、name、value三个私有字段全部为只读体现了它纯数据查询的定位。核心 API 详解id / name / value 三个方法EnvVariable对外暴露三个异步方法全部返回Promise这与 Dagger 的惰性求值模型一致——调用方法时才真正向引擎发起 GraphQL 查询。id(): PromiseEnvVariableIDA unique identifier for this EnvVariable.返回该环境变量对象的唯一标识符。其类型为EnvVariableID在 EnvVariableID 类型别名文档 中定义为type EnvVariableID string { __EnvVariableID: never }它是一个以string为基础、通过__EnvVariableID: never做名义类型标记nominal typing的标量类型用于在编译期防止不同类型的 ID 相互混用。id()通常用于持久化场景——例如把某个环境变量对象的 ID 保存下来后续通过client.loadEnvVariableFromID(id)重新加载若 SDK 暴露了对应加载方法从而避免反复重建查询链路。name(): PromisestringThe environment variable name.返回环境变量的名称Key例如PATH、FOO。这是区分不同环境变量的唯一标识。value(): PromisestringThe environment variable value.返回环境变量的值Value例如/usr/local/sbin:/usr/local/bin。需要注意Dagger 中的EnvVariable仅表示持久化在容器配置image config /withEnvVariable写入中的环境变量它并不包含容器运行时如withExec中env参数注入的临时变量产生的全部环境。构造函数仅供内部使用Constructor is used for internal usage only, do not create object from it.构造函数签名为new EnvVariable(ctx?, _id?, _name?, _value?)其中ctx?: Context为 Dagger 查询上下文其余三个下划线前缀参数分别对应该对象缓存的 ID、名称和值。文档明确警告不要自行 new 该对象实例只能由 SDK 内部如Container.envVariables()构造。EnvVariable 从何而来与 Container API 的配套关系EnvVariable永远不会独立存在它总是作为Container的查询结果出现。理解它必须先理解配套的三个Container方法均在同一份 client.gen.ts 中生成1. 写入withEnvVariable(name, value, opts?)withEnvVariable 用于在容器中设置一个新的环境变量返回一个新的Container不可变快照语义签名如下withEnvVariable ( name: string, value: string, opts?: ContainerWithEnvVariableOpts, ): Container { const ctx this._ctx.select(withEnvVariable, { name, value, ...opts }) return new Container(ctx) }参数说明name环境变量名如HOSTvalue环境变量值如localhostopts.expand是否展开值中的$VAR/${VAR}详见下文 expand 一节。2. 查询单个envVariable(name): PromisestringenvVariable 按名称直接返回字符串值注意返回的不是EnvVariable对象而是string适合只关心某个变量的值的场景envVariable async (name: string): Promisestring { if (this._envVariable) { return this._envVariable } const ctx this._ctx.select(envVariable, { name }) const response: Awaitedstring await ctx.execute() return response }3. 查询列表envVariables(): PromiseEnvVariable[]envVariables 返回EnvVariable[]数组是唯一合法获取EnvVariable实例的入口。其实现体现了 Dagger 的查询优化技巧——先只请求每个元素的id再通过selectNode按 ID 重建各自的查询上下文从而让后续对name()/value()的调用可以按需懒加载envVariables async (): PromiseEnvVariable[] { type envVariables { id: ID } const ctx this._ctx.select(envVariables).select(id) const response: AwaitedenvVariables[] await ctx.execute() return response.map( (r) new EnvVariable(ctx.copy().selectNode(r.id, EnvVariable)), ) }expand 选项$VAR 展开机制的源码级解读EnvVariable的值可以是字面值也可以是引用其他变量的模板。何时展开由 ContainerWithEnvVariableOpts 中的expand?布尔选项控制Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g. /opt/bin:$PATH).即当expand: true时withEnvVariable(PATH_EXT, /opt/bin:$PATH)会把$PATH展开为容器当前已有的PATH值expand缺省为false值中的$VAR会原样保留此时$不会转义通常需要手动写\$或直接使用字面值。底层实现位于引擎侧 core/container.go 的ExpandContainerInputfunc ExpandContainerInput(container *Container, input string, expand bool) (string, error) { if !expand { return input, nil } // 收集容器中的 Secret 与 volatile 环境变量禁止对其展开 expanded : os.Expand(input, func(k string) string { if slices.Contains(secretEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with secret env variable %q, k) return } if slices.Contains(volatileEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with volatile env variable %q, k) return } v, _ : LookupEnv(container.Config.Env, k) return v }) // ... }从源码可以归纳出三个关键实现事实展开基于os.Expand支持$VAR与${VAR}两种写法查找范围是容器的Config.Env即当前容器配置中已持久化的环境变量而不是宿主机环境Secret 与 volatile 变量禁止展开若引用了密钥类或易变volatile环境变量引擎会直接报错expand cannot be used with secret env variable/expand cannot be used with volatile env variable这是一种安全设计避免把敏感值意外拼入普通环境变量。引擎侧持久化该操作时也记录了Expand字段见 core/container.go 中的persistedContainerWithEnvVariableLazy。另外需要注意EnvVariable对象本身展示的是展开后的持久化值envVariables()不会返回容器内 secret 注入的临时变量Secret 在 Dagger 中由独立的Secret类型管理不混入EnvVariable列表。实战示例完整可运行的 TypeScript 代码下面是一个基于alpine镜像、覆盖写入 → 展开 → 列表 → 单项读取全流程的示例import { connect } from dagger.io/dagger connect(async (client) { const ctr client .container() .from(alpine:3.16.2) .withEnvVariable(FOO, TCP) // 字面值 .withEnvVariable(BAR, BOOL) .withEnvVariable(PATH_EXT, /opt/bin:$PATH, { expand: true }) // 展开 $PATH // 1) 按名称读取单个变量返回 string const foo await ctr.envVariable(FOO) console.log(FOO , foo) // TCP // 2) 读取全部持久化环境变量返回 EnvVariable[] const envs await ctr.envVariables() for (const env of envs) { console.log(await env.name(), , await env.value()) } // 3) 在 exec 中使用这些变量验证展开结果 const out await ctr.withExec([printenv, PATH_EXT]).stdout() console.log(PATH_EXT , out.trim()) })注意envVariables()返回的元素类型是EnvVariable需要分别调用其name()与value()均为异步方法才能拿到实际值而envVariable(name)一步到位返回string。若你只需要一个变量的值优先用后者能少一次 GraphQL 往返。测试用例佐证SDK 中的真实行为仓库自带的 SDK 测试 sdk/typescript/src/api/test/api.spec.ts 印证了上述行为链式写入const env (c: Container): Container c.withEnvVariable(FOO, bar)L260-L263说明withEnvVariable返回新容器、可参与函数组合空值与 exec 可见性withEnvVariable(FOO, )之后执行withExec([printenv, FOO])输出为空行L296-L302证明空字符串也是合法值且会被 exec 看到列表遍历连续设置FOOBAR、BARBOOL后调用ctr.envVariables()逐一断言L366-L372与上文envVariables()的用法完全一致单项读取withEnvVariable(FOO, TCP)后envVariable(FOO)断言等于TCPL388-L394。小结与使用建议EnvVariable是 Dagger TypeScript SDK 中最基础的数据对象之一设计极其克制它只回答容器里持久化了哪些环境变量、叫什么、值是什么这三个问题。实践中请记住四条准则不要手动new EnvVariable只通过Container.envVariables()获取实例取单个值用Container.envVariable(name)返回string取全量再遍历EnvVariable的name()/value()涉及$VAR展开时显式传{ expand: true }且不要尝试展开 Secret 或 volatile 变量引擎会拒绝执行该对象只反映持久化配置容器运行期动态产生的临时环境不在此列。相关 API 文档与源码索引类定义见 EnvVariable 类文档 与 client.gen.tsID 类型见 EnvVariableID展开语义可继续深入引擎源码 core/container.go 与 SDK 测试 api.spec.ts。【免费下载链接】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），仅供参考