Dagger TypeScript SDKContainerWithEnvVariableOpts详解withEnvVariable 的环境变量展开expand机制【免费下载链接】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导读ContainerWithEnvVariableOpts是 Dagger 容器 API 中与Container.withEnvVariable()配套的选项对象其唯一可选属性expand控制是否在写入环境变量前根据容器内已定义的当前环境变量对值做$VAR/${VAR}展开。本文以docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases/ContainerWithEnvVariableOpts.md为骨架结合 TypeScript SDK 生成代码、Go 核心引擎实现与集成测试完整讲解该选项的类型定义、使用姿势、底层实现原理与行为边界帮助你安全、精准地构造容器环境变量。类型别名定义在 TypeScript SDK 中ContainerWithEnvVariableOpts是一个以object为基的类型别名定义于 sdk/typescript/src/api/client.gen.tsexport type ContainerWithEnvVariableOpts { /** * Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g. /opt/bin:$PATH). */ expand?: boolean }它作为Container.withEnvVariable的第三个可选参数出现完整签名同样位于 sdk/typescript/src/api/client.gen.tswithEnvVariable ( name: string, value: string, opts?: ContainerWithEnvVariableOpts, ): Container { const ctx this._ctx.select(withEnvVariable, { name, value, ...opts }) return new Container(ctx) }该 opts 对象最终与name、value一起被序列化为 GraphQL 参数传给引擎this._ctx.select(withEnvVariable, { name, value, ...opts })因此它本质上是 GraphQL 字段withEnvVariable的可选参数expand的类型封装。属性详解expandexpand?:boolean可选默认未启用作用当值为true时Dagger 会在把value写入容器镜像的Env之前按照容器当前已定义的环境变量对其中出现的$VAR或${VAR}进行展开替换。典型场景需要基于既有变量拼接新值例如给PATH追加一个目录值写为/opt/bin:$PATH展开后变成/opt/bin后接原有的PATH内容。默认行为expand未传或传false时值会**原样字面量**写入$、${}不会被解释。展开的两条来源展开所依赖的当前环境变量由两条路径组成均以容器当前状态为准镜像配置Config.Env即此前通过withEnvVariable、withEnvFileVariables等 API 设置且随镜像配置持久化的环境变量运行时容器状态引擎在求值withEnvVariable时基于父容器快照读取上述Config.Env再执行展开。也就是说展开是链式的——先设置的变量可以在后设置的变量中被引用这为多阶段配置PATH、LD_LIBRARY_PATH等衍生变量提供了便利。使用示例TypeScript / JavaScriptimport { Client, connect } from dagger.io/dagger connect(async (client: Client) { // 1) 先定义 USER_PATH const c1 client.container() .from(alpine) .withEnvVariable(USER_PATH, /opt) // 2) 用 expand 展开 ${USER_PATH}并把原有 PATH 追加到末尾 const c2 c1.withEnvVariable( PATH, ${USER_PATH}/bin:$PATH, { expand: true }, ) // 验证输出 /opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin const out await c2.withExec([printenv, PATH]).stdout() console.log(out) })Go SDK同样的能力在 Go SDK 中以dagger.ContainerWithEnvVariableOpts暴露定义于 sdk/go/dagger.gen.gotype ContainerWithEnvVariableOpts struct { // Replace ${VAR} or $VAR in the value according to the current // environment variables defined in the container (e.g. /opt/bin:$PATH). Expand bool } ctr, err : client.Container(). From(alpine). WithEnvVariable(USER_PATH, /opt). WithEnvVariable(PATH, ${USER_PATH}/bin:$PATH, dagger.ContainerWithEnvVariableOpts{Expand: true}). WithExec([]string{printenv, PATH}). Stdout(ctx)底层 GraphQLexpand对应 GraphQL 字段withEnvVariable的可选参数其 schema 定义见 core/schema/testdata/base_schema.graphqlsname: String!、value: String!之后即为expand参数。手动调用 GraphQL 时写法如下{ container { from(address: alpine) { withEnvVariable(name: PATH, value: ${USER_PATH}/bin:$PATH, expand: true) { withExec(args: [printenv, PATH]) { stdout } } } } }源码级原理展开实现ExpandContainerInputexpand的展开逻辑集中在核心引擎函数ExpandContainerInput位于 core/container.gofunc ExpandContainerInput(container *Container, input string, expand bool) (string, error) { if !expand { return input, nil } // 收集 secret 与 volatile 环境变量的名字 secretEnvs : []string{} for _, secret : range container.Secrets { secretEnvs append(secretEnvs, secret.EnvName) } volatileEnvs : []string{} WalkEnv(container.VolatileEnv, func(name, _, _ string) { volatileEnvs append(volatileEnvs, name) }) var secretEnvFoundError error 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 }) if secretEnvFoundError ! nil { return , secretEnvFoundError } return expanded, nil }可以从中确认几个关键事实expandfalse直接短路值原样返回不做任何解析展开由 Go 标准库os.Expand完成它同时支持$VAR与${VAR}两种语法未定义变量的处理LookupEnv在Config.Env中找不到的变量返回空字符串因此未定义引用会被展开为空这是os.Expand的语义组合PATH时需留意不要引用拼写错误的变量与 Secret/Volatile 变量的互斥若值中引用了容器内的 secret 环境变量或 volatile 环境变量WithVolatileVariable设置的变量展开会直接返回错误expand cannot be used with secret env variable .../... volatile env variable ...。原因是这两类变量的值不能进入镜像配置的Env也就无法参与展开。这是最容易踩坑的限制之一。写入镜像配置AddEnv展开完成后Dagger 通过UpdateImageConfig修改 OCI 镜像配置并调用core.AddEnv(cfg.Env, args.Name, value)将新变量加入Config.Env见 core/schema/container.go。AddEnv定义于 core/util.go其行为是若同名变量已存在则覆盖否则追加。也就是说withEnvVariableexpand本质上是先展开、后写入或覆盖镜像环境配置。惰性求值与缓存schema层的withEnvVariable在父容器为惰性pending lazy状态时会记录一个ContainerWithEnvVariableLazy节点core/container.go把Name、Value、Expand连同父容器引用一起保存直到真正需要时才求值。这意味着展开发生时读取的是求值时刻的父容器环境链式引用能拿到此前设置的最新值该操作参与 Dagger 的图缓存相同的父容器、name、value、expand组合会被缓存复用这也解释了为什么官方建议不要用环境变量做缓存破坏cache busting——参见集成测试中WithEnvVariable(CACHEBUSTER, identity.NewID())的用法core/integration/cache_test.go 等。行为边界与注意事项场景行为依据不传expand或传false值按字面量写入$不解释core/container.go传expand: true引用已定义变量用当前Config.Env中的值替换os.ExpandLookupEnv引用未定义变量替换为空字符串LookupEnv返回空引用 secret / volatile 变量返回错误操作失败core/container.go变量名含特殊字符推荐使用${VAR}形式$VAR形式按 Goos.Expand规则贪婪匹配字母、数字、下划线sdk/typescript/src/api/client.gen.ts两点实操建议拼接路径类值时优先使用${VAR}${USER_PATH}/bin:$PATH语义最清晰$PATH出现在串尾没有问题但若变量名后紧跟字母数字如$PATHfooos.Expand会把它当作名为PATHfoo的变量产生非预期结果。避免对 secret 或 volatile 变量使用 expand需要引用 secret 的值时应直接把 secret 挂到容器上withSecretVariable而不是试图通过expand拼接引用 volatile 变量同理。集成测试验证引擎自带的集成测试TestWithEnvVariableExpand精确刻画了默认与展开两种行为见 core/integration/container_test.go不展开WithEnvVariable(FOO, foo:$PATH)后printenv FOO输出字面量foo:$PATH展开先WithEnvVariable(USER_PATH, /opt)再WithEnvVariable(PATH, ${USER_PATH}/bin:$PATH, dagger.ContainerWithEnvVariableOpts{Expand: true})printenv PATH输出/opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin。该测试直接对应本主题可作为行为契约来回归验证expand的语义。相关 API 对照withEnvFileVariables从 env-file 批量导入环境变量不涉及展开见 sdk/typescript/src/api/client.gen.tsContainerWithExecOpts.expandwithExec也提供同名expand选项用于对**执行参数args**而非环境变量值做展开sdk/typescript/src/api/client.gen.ts二者的底层展开逻辑同为ExpandContainerInputcore/container.go 中resolveContainerInputPath的复用即为佐证。小结ContainerWithEnvVariableOpts虽只有一个expand属性但背后牵涉到 Dagger 引擎的镜像配置管理、os.Expand展开语义、惰性求值与 secret/volatile 互斥等实现细节。掌握默认字面量、开启即展开、引用当前容器环境、secret/volatile 禁用这四条规则即可安全地在流水线中动态组合PATH、LD_LIBRARY_PATH等派生环境变量避免手工拼接带来的可移植性问题。【免费下载链接】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 `ContainerWithEnvVariableOpts` 详解：withEnvVariable 的环境变量展开（expand）机制
Dagger TypeScript SDKContainerWithEnvVariableOpts详解withEnvVariable 的环境变量展开expand机制【免费下载链接】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导读ContainerWithEnvVariableOpts是 Dagger 容器 API 中与Container.withEnvVariable()配套的选项对象其唯一可选属性expand控制是否在写入环境变量前根据容器内已定义的当前环境变量对值做$VAR/${VAR}展开。本文以docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases/ContainerWithEnvVariableOpts.md为骨架结合 TypeScript SDK 生成代码、Go 核心引擎实现与集成测试完整讲解该选项的类型定义、使用姿势、底层实现原理与行为边界帮助你安全、精准地构造容器环境变量。类型别名定义在 TypeScript SDK 中ContainerWithEnvVariableOpts是一个以object为基的类型别名定义于 sdk/typescript/src/api/client.gen.tsexport type ContainerWithEnvVariableOpts { /** * Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g. /opt/bin:$PATH). */ expand?: boolean }它作为Container.withEnvVariable的第三个可选参数出现完整签名同样位于 sdk/typescript/src/api/client.gen.tswithEnvVariable ( name: string, value: string, opts?: ContainerWithEnvVariableOpts, ): Container { const ctx this._ctx.select(withEnvVariable, { name, value, ...opts }) return new Container(ctx) }该 opts 对象最终与name、value一起被序列化为 GraphQL 参数传给引擎this._ctx.select(withEnvVariable, { name, value, ...opts })因此它本质上是 GraphQL 字段withEnvVariable的可选参数expand的类型封装。属性详解expandexpand?:boolean可选默认未启用作用当值为true时Dagger 会在把value写入容器镜像的Env之前按照容器当前已定义的环境变量对其中出现的$VAR或${VAR}进行展开替换。典型场景需要基于既有变量拼接新值例如给PATH追加一个目录值写为/opt/bin:$PATH展开后变成/opt/bin后接原有的PATH内容。默认行为expand未传或传false时值会**原样字面量**写入$、${}不会被解释。展开的两条来源展开所依赖的当前环境变量由两条路径组成均以容器当前状态为准镜像配置Config.Env即此前通过withEnvVariable、withEnvFileVariables等 API 设置且随镜像配置持久化的环境变量运行时容器状态引擎在求值withEnvVariable时基于父容器快照读取上述Config.Env再执行展开。也就是说展开是链式的——先设置的变量可以在后设置的变量中被引用这为多阶段配置PATH、LD_LIBRARY_PATH等衍生变量提供了便利。使用示例TypeScript / JavaScriptimport { Client, connect } from dagger.io/dagger connect(async (client: Client) { // 1) 先定义 USER_PATH const c1 client.container() .from(alpine) .withEnvVariable(USER_PATH, /opt) // 2) 用 expand 展开 ${USER_PATH}并把原有 PATH 追加到末尾 const c2 c1.withEnvVariable( PATH, ${USER_PATH}/bin:$PATH, { expand: true }, ) // 验证输出 /opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin const out await c2.withExec([printenv, PATH]).stdout() console.log(out) })Go SDK同样的能力在 Go SDK 中以dagger.ContainerWithEnvVariableOpts暴露定义于 sdk/go/dagger.gen.gotype ContainerWithEnvVariableOpts struct { // Replace ${VAR} or $VAR in the value according to the current // environment variables defined in the container (e.g. /opt/bin:$PATH). Expand bool } ctr, err : client.Container(). From(alpine). WithEnvVariable(USER_PATH, /opt). WithEnvVariable(PATH, ${USER_PATH}/bin:$PATH, dagger.ContainerWithEnvVariableOpts{Expand: true}). WithExec([]string{printenv, PATH}). Stdout(ctx)底层 GraphQLexpand对应 GraphQL 字段withEnvVariable的可选参数其 schema 定义见 core/schema/testdata/base_schema.graphqlsname: String!、value: String!之后即为expand参数。手动调用 GraphQL 时写法如下{ container { from(address: alpine) { withEnvVariable(name: PATH, value: ${USER_PATH}/bin:$PATH, expand: true) { withExec(args: [printenv, PATH]) { stdout } } } } }源码级原理展开实现ExpandContainerInputexpand的展开逻辑集中在核心引擎函数ExpandContainerInput位于 core/container.gofunc ExpandContainerInput(container *Container, input string, expand bool) (string, error) { if !expand { return input, nil } // 收集 secret 与 volatile 环境变量的名字 secretEnvs : []string{} for _, secret : range container.Secrets { secretEnvs append(secretEnvs, secret.EnvName) } volatileEnvs : []string{} WalkEnv(container.VolatileEnv, func(name, _, _ string) { volatileEnvs append(volatileEnvs, name) }) var secretEnvFoundError error 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 }) if secretEnvFoundError ! nil { return , secretEnvFoundError } return expanded, nil }可以从中确认几个关键事实expandfalse直接短路值原样返回不做任何解析展开由 Go 标准库os.Expand完成它同时支持$VAR与${VAR}两种语法未定义变量的处理LookupEnv在Config.Env中找不到的变量返回空字符串因此未定义引用会被展开为空这是os.Expand的语义组合PATH时需留意不要引用拼写错误的变量与 Secret/Volatile 变量的互斥若值中引用了容器内的 secret 环境变量或 volatile 环境变量WithVolatileVariable设置的变量展开会直接返回错误expand cannot be used with secret env variable .../... volatile env variable ...。原因是这两类变量的值不能进入镜像配置的Env也就无法参与展开。这是最容易踩坑的限制之一。写入镜像配置AddEnv展开完成后Dagger 通过UpdateImageConfig修改 OCI 镜像配置并调用core.AddEnv(cfg.Env, args.Name, value)将新变量加入Config.Env见 core/schema/container.go。AddEnv定义于 core/util.go其行为是若同名变量已存在则覆盖否则追加。也就是说withEnvVariableexpand本质上是先展开、后写入或覆盖镜像环境配置。惰性求值与缓存schema层的withEnvVariable在父容器为惰性pending lazy状态时会记录一个ContainerWithEnvVariableLazy节点core/container.go把Name、Value、Expand连同父容器引用一起保存直到真正需要时才求值。这意味着展开发生时读取的是求值时刻的父容器环境链式引用能拿到此前设置的最新值该操作参与 Dagger 的图缓存相同的父容器、name、value、expand组合会被缓存复用这也解释了为什么官方建议不要用环境变量做缓存破坏cache busting——参见集成测试中WithEnvVariable(CACHEBUSTER, identity.NewID())的用法core/integration/cache_test.go 等。行为边界与注意事项场景行为依据不传expand或传false值按字面量写入$不解释core/container.go传expand: true引用已定义变量用当前Config.Env中的值替换os.ExpandLookupEnv引用未定义变量替换为空字符串LookupEnv返回空引用 secret / volatile 变量返回错误操作失败core/container.go变量名含特殊字符推荐使用${VAR}形式$VAR形式按 Goos.Expand规则贪婪匹配字母、数字、下划线sdk/typescript/src/api/client.gen.ts两点实操建议拼接路径类值时优先使用${VAR}${USER_PATH}/bin:$PATH语义最清晰$PATH出现在串尾没有问题但若变量名后紧跟字母数字如$PATHfooos.Expand会把它当作名为PATHfoo的变量产生非预期结果。避免对 secret 或 volatile 变量使用 expand需要引用 secret 的值时应直接把 secret 挂到容器上withSecretVariable而不是试图通过expand拼接引用 volatile 变量同理。集成测试验证引擎自带的集成测试TestWithEnvVariableExpand精确刻画了默认与展开两种行为见 core/integration/container_test.go不展开WithEnvVariable(FOO, foo:$PATH)后printenv FOO输出字面量foo:$PATH展开先WithEnvVariable(USER_PATH, /opt)再WithEnvVariable(PATH, ${USER_PATH}/bin:$PATH, dagger.ContainerWithEnvVariableOpts{Expand: true})printenv PATH输出/opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin。该测试直接对应本主题可作为行为契约来回归验证expand的语义。相关 API 对照withEnvFileVariables从 env-file 批量导入环境变量不涉及展开见 sdk/typescript/src/api/client.gen.tsContainerWithExecOpts.expandwithExec也提供同名expand选项用于对**执行参数args**而非环境变量值做展开sdk/typescript/src/api/client.gen.ts二者的底层展开逻辑同为ExpandContainerInputcore/container.go 中resolveContainerInputPath的复用即为佐证。小结ContainerWithEnvVariableOpts虽只有一个expand属性但背后牵涉到 Dagger 引擎的镜像配置管理、os.Expand展开语义、惰性求值与 secret/volatile 互斥等实现细节。掌握默认字面量、开启即展开、引用当前容器环境、secret/volatile 禁用这四条规则即可安全地在流水线中动态组合PATH、LD_LIBRARY_PATH等派生环境变量避免手工拼接带来的可移植性问题。【免费下载链接】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），仅供参考